📞 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:

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').

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.

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.

await webrtc.rejoinCall("existing_call_id");

4. Send User Context

Send contextual information about the user to the backend.

webrtc.sendUserContext({
  name: "User Name",
  email: "[email protected]",
  customData: "some-value"
});

5. Global Ringtone Setting

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

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).

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

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).

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