@messagebird/webrtc

JavaScript WebRTC SDK

Initializing an RTC Client

To enable your application to make and receive calls over WebRTC, you have to instantiate a new WebRTCClient (TODO: good name? Device). To instantiate a client and authenticate with your MessageBird account you need to generate a JWT and pass it to the client (docs)

const client = new WebRTCClient({
  username: 'test',
  jwt: 'test',
});

// Open a connection to the MessageBird WebRTC API
client
  .connect()
  .then(() => {
    // Ready to start and receive WebRTC connections.
  })
  .catch(error => {
    // Error making a connection. The error object contains details of the failure.
  });

Starting a new call

Make sure you've instantiated the WebRTCClient and opened the connection by calling the .connect() method. After succesfully instantiating a new client you can start new RTC sessions by calling the starRTCSession method. (todo: better naming? connect/setup/call? )

client
  .startAudioCall({
    to: '[phone]', // TODO: This will become `flowId` probably?
    onEnded() {
      console.log('session was ended');
    },
  })
  .then(connection => {
    // resolves with an `RTCConnection` object (docs)
  })
  .catch(error => {
    // Failed to start a session, error object contains details.
  });

Handling incoming connections

Your app can handle incoming RTC connections by handling the on('incoming') event.

client.on('incoming', connection => {
  connection.accept(); // Accept the incoming connection and start a call

  connection.disconnect(); // Reject the incoming connection.
});

API Reference

Check out the TS Typings: https://gitlab.messagebird.io/frontend/javascript-webrtc-sdk/tree/master/types

WebRTCClient

constructor(options)

Creates a new instance of the WebRTCClient. Accepts an options object with the following properties:

• username alphanumeric username to identify to the SIP server (todo: do we need this? it's for connecting to sip:{username}@webrtc-staging.messagebird.io )
• jwt JWT to authenticate. How to generate?

connect()

Connect the WebRTCClient to start making outbound calls or listen for incoming sessions

• returns a promise that resolves when the client is connected. Rejects with an error when connection fails.

startAudioCall(options)

Start a new outgoing RTC session. Accepts an options object with the following properties:

• to The recipient to connect to. TODO: Should become flowId?

• onEnded Function that will be called when the session ends. (disconnected by user or remote)

• returns a promise that resolves with an RTCSession when the call is started. Rejects if starting the connection failed.

events

on('connected', handler)

When the client connects. Can be called multiple times in case the client disconnects and automatically reconnects.

on('disconnected', handler)

When the client disconnects for a certain reason. (docs on data object with reason)

on('incoming', handler)

Fired when an incoming RTC session is received. Callback contains an RTCSession object.

client.on('incoming', incomingSession => {
  // Accept the incoming call
  incomingSession.accept();
});

RTCSession

The RTCSession object describes an ongoing RTC session. You will never instantiate an RTCSession yourself, the SDK will take care of that for you.

disconnect()

Disconnects the client from the RTC session (todo: maybe rename?)

on(name, handler)

Bind a new event listener. See Events (link) below

removeEventListener(name, handler)

Removes an event listener

Events

on('confirmed')

Fired when an outgoing session is confirmed by the other party (todo: how does this behave with ringing state?)

on('failed')

Fired when an RTC session fails. Callback contains an error object with details

on('ended')

Fired when an RTC session ends normally (todo: "normally"? How does this work if remote hangs up)

IncomingRTCSession

IncomingRTCSession extends everything from RTCSession, but has some additional features

acccept()

Accept an incoming connection to start a call.