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 using the MSG91 infrastructure.

# 📞 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 using the MSG91 infrastructure.

## 📦 Installation

Install the package using npm or yarn:

```bash
npm install msg91-webrtc-call
# or
yarn add msg91-webrtc-call
```

## 🚀 Getting Started

### 1. Initialization

Initialize the WebRTC instance with your user token. You can optionally specify the environment ('prod', 'test', 'dev').

```javascript
import WebRTC from "msg91-webrtc-call";

// Initialize with your user token
const userToken = "YOUR_USER_TOKEN";
const webrtc = WebRTC(userToken, "prod"); // Defaults to "prod"
```

### 2. Initiate a Call

To start a new call, you need a valid call token.

```javascript
const callToken = "YOUR_CALL_TOKEN";
await webrtc.call(callToken);
```

### 3. Rejoin an Ongoing Call

If a user gets disconnected, they can rejoin the call using the call ID.

```javascript
await webrtc.rejoinCall("existing_call_id");
```

### 4. Send User Context

Send contextual information about the user to the backend.

```javascript
webrtc.sendUserContext({
  name: "User Name",
  email: "user@email.com",
  customData: "some-value"
});

```
### 5. Global Ringtone Setting
```javascript
webrtc.silence(true);   // Stop sending PLAY_RINGTONE event
webrtc.silence(false);  // Start sending PLAY_RINGTONE event
```

## 🎧 Handling Calls & Events

The `WebRTC` instance emits events that you should listen to for handling call flows.

### Listening for Events

```javascript
import { WebRTC_EVENT } from "msg91-webrtc-call";

// Handle Incoming Calls
webrtc.on(WebRTC_EVENT.INCOMING_CALL, (incomingCall) => {
    console.log("Incoming call from:", incomingCall.getInfo().from);
    
    // Handle UI for incoming call
    incomingCall.accept(); // or incomingCall.reject();
});

// Handle Outgoing Calls
webrtc.on(WebRTC_EVENT.OUTGOING_CALL, (outgoingCall) => {
    console.log("Dialing...");
});

// Ringtone Management
webrtc.on(WebRTC_EVENT.PLAY_RINGTONE, () => {
    // Play your ringtone audio
    audioElement.play();
});

webrtc.on(WebRTC_EVENT.STOP_RINGTONE, () => {
    // Stop your ringtone audio
    audioElement.pause();
    audioElement.currentTime = 0;
});
```

## 📘 Call Object API

Both `IncomingCall` and `OutgoingCall` share common methods and events.

### Common Methods

- `getInfo()`: Returns `CallInfo` containing `id`, `from`, `to`, `type`.
- `mute()`: Mutes the user's audio.
- `unmute()`: Unmutes the user's audio.
- `hang()`: Ends the call.
- `getMediaStream()`: Returns the `MediaStream` object.
- `getStatus()`: Returns current status (`idle`, `ringing`, `connected`, `ended`).

### IncomingCall Specifics

- `accept()`: Answers the call.
- `reject()`: Rejects the call.
- `silence(status: boolean)`: Silences the ringtone for this specific call.

### OutgoingCall Specifics

- `cancel()`: Cancels the call before it is answered.
- `sendMessage(message: MessageArray)`: Sends a message (e.g., to a bot).

### Call Events

Listen to these events on the `call` object (both incoming and outgoing).

```javascript
import { CALL_EVENT } from "msg91-webrtc-call";

call.on(CALL_EVENT.CONNECTED, (mediaStream) => {
    // Call connected, attach mediaStream to an audio element
    const audioRef = document.getElementById("audio-element");
    audioRef.srcObject = mediaStream;
    audioRef.play();
});

call.on(CALL_EVENT.ENDED, (payload) => {
    console.log("Call ended", payload);
});

call.on(CALL_EVENT.ANSWERED, (payload) => {
    console.log("Call answered by", payload.answeredBy);
});

call.on(CALL_EVENT.ERROR, (error) => {
    console.error("Call error", error);
});

// For incoming calls
call.on(CALL_EVENT.UNAVAILABLE, () => {
    console.log("Call picked up by another device or cancelled");
});
```

## ⚛️ React Integration Example

```javascript
import { useEffect, useState, useRef } from "react";
import WebRTC, { WebRTC_EVENT, CALL_EVENT } from "msg91-webrtc-call";

const CallComponent = ({ userToken }) => {
  const [call, setCall] = useState(null);
  const webrtcRef = useRef(null);

  useEffect(() => {
    if (!userToken) return;

    const webrtc = WebRTC(userToken);
    webrtcRef.current = webrtc;

    webrtc.on(WebRTC_EVENT.INCOMING_CALL, (incomingCall) => {
      setCall(incomingCall);
    });
    
    // Cleanup
    return () => {
        // The WebRTC instance is a singleton. 
        // Calling webrtc.close() would disconnect the socket for the entire session.
        // Only close if you are sure the user is logging out or leaving the app.
        // webrtc.close(); 
    };
  }, [userToken]);

  const handleAccept = () => {
    if (call) {
        call.accept();
        call.on(CALL_EVENT.CONNECTED, (stream) => {
            // Attach stream to audio element
        });
    }
  };

  return (
    <div>
      {call && <button onClick={handleAccept}>Accept Call</button>}
    </div>
  );
};
```

## 🔧 Types & Enums

The library exports several useful types and enums:

- `WebRTC_EVENT`: Events emitted by the main `WebRTC` instance.
- `CALL_EVENT`: Events emitted by `Call` instances.
- `CALL_STATUS`: Status of the call (`idle`, `ringing`, `connected`, `ended`).
- `CALL_TYPE`: Type of call (`incoming-call`, `outgoing-call`).

```javascript
import { WebRTC_EVENT, CALL_EVENT, CALL_STATUS } from "msg91-webrtc-call";
```