msg91-webrtc-call/README.md

**msg91-webrtc-call** is a lightweight JavaScript SDK that enables you to easily add peer-to-peer WebRTC audio/video calling functionality to your web applications.

## **📞 msg91-webrtc-call**
**msg91-webrtc-call** is a lightweight JavaScript SDK that enables you to easily add peer-to-peer WebRTC audio/video calling functionality to your web applications.

With a simple API, it helps you initiate and receive calls, manage call states, and access media streams in real-time.

## **📦 Installation**
Install the package using npm or yarn:
```bash
npm install msg91-webrtc-call
# or
yarn add msg91-webrtc-call
```

## **🚀 Getting Started**
### **1. Initialization**
Start by importing the library and initializing a WebRTC instance with your user ID and display name:
```javascript
import WebRTC from "msg91-webrtc-call";
/** User Token Schema
  const userTokenSchema = {
        id: string,
        name: string,
        picture?: string
    }
 */
const webrtc = WebRTC(userToken);
```

### **2. Initiate a Call**
You can initiate a call to one or more recipients using the call method.
```javascript
/** Call Token Schema
 const callTokenSchema = {
    id: string, // call_id
    from: {
        id: string, // user_id
        name: string,
        picture?: string
    },
    to: {
        id: string, // user_id
        name: string,
        picture?: string
    }[]
}
 */
webrtc.call(callToken);
```
callId is a unique identifier for the call.

The second parameter is an array of recipients with id, name, and picture.

### **3. Rejoin an Ongoing Call**
```javascript
webrtc.rejoinCall(callId);
```

### **4. Send User Context**
```javascript
webrtc.sendUserContext({
  "name": "User Name",
  "email": "user@email.com",
  "admin": "true"
});
```

## **🎧 Handling Calls**
### Incoming Call
Listen for incoming calls using the on("call") event:
```javascript
webrtc.on("call", (call) => {
  const isIncoming = call.type === "incoming-call";
  if (!isIncoming) return;

  call.getInfo(); // Get call details

  // Accept or reject the call
  call.accept();
  call.reject();

  // Mute / Unmute
  call.mute();
  call.unmute();

    // Hang the call
    call.hang();

  // Access media streams
  const media = call.getMediaStream();

    // Events
  call.on("ended", (data)=>{

  });
    // This call can't be connected for some reason i.e someone else has already answered the call
  call.on("unavailable", (data)=>{

  });

  call.on("rejoined", (data)=>{
    const summary = data?.summary;
    /**
     * Following details can be found in summary to rehydrate the UI
     * summary.startedAt;
     * summary.answeredAt;
     * summary.answeredBy;
     */
  });


  call.on("error", (error)=>{
    // Show error to user
  });
});

```

### Outgoing Call
You can also manage your outgoing calls using the same on("call") listener:
```javascript
webrtc.on("call", (call) => {
  const isOutgoing = call.type === "outgoing-call";
  if (!isOutgoing) return;

  call.getInfo(); // Get call details

  // Cancel the call
  call.cancel();

  // Mute / Unmute
  call.mute();
  call.unmute();

  // Hang the call
  call.hang();
    
  // Access media streams
  const media = call.getMediaStream();


  // Events
  call.on("answered", (data)=>{

  });

  call.on("ended", (data)=>{

  });
  call.on("connected", (mediaStream)=>{

  });

    call.on("rejoined", (data)=>{
    const summary = data?.summary;
    /**
     * Following details can be found in summary to rehydrate the UI
     * summary.startedAt;
     * summary.answeredAt;
     * summary.answeredBy;
     */
  });

  call.on("mute", ({uid})=>{

  });
  call.on("unmute", ({uid})=>{

  });
});
```
## **📘 API Reference**
Initialization
WebRTC(uid: string, name: string): WebRTCInstance

### Methods
webrtc.call(callId: string, recipients: Array<{ id, name, picture }>)

webrtc.on("call", (call) => { ... })

Call Object
call.type: "incoming-call" or "outgoing-call"

call.getInfo(): Fetches call metadata

call.accept(): Accepts the call

call.reject(): Rejects the call

call.cancel(): Cancels an outgoing call

call.mute(): Mutes your microphone

call.unmute(): Unmutes your microphone

call.getMediaStream(): Returns the media stream

## **⚛️ React Integration **
Use this in a React component with proper cleanup:
```javascript
import { useEffect } from "react";
import WebRTC from "msg91-webrtc-call";

const CallComponent = ({ user }) => {
  useEffect(() => {
    if (!user) return;

    const webrtc = WebRTC(user.id, user.name);

    const handleCall = (call) => {
      if (call.type === "incoming-call") {
        // Handle incoming
        call.accept();
      }
    };

    webrtc.on("call", handleCall);

    return () => {
      // Optional: clean up if needed
    };
  }, [user]);

  return <div>Ready to receive calls</div>;
};

```
## **🏁 Conclusion**
msg91-webrtc-call simplifies WebRTC integration by offering a clean and developer-friendly API. Whether you're building customer support features, team meetings, or peer-to-peer chat apps, this SDK gets you up and running with minimal effort.

Start building real-time audio/video experiences with just a few lines of code!