@messagebird/webrtc

JavaScript WebRTC SDK

Getting started with developing

• Clone the repo
• yarn && yarn build -w to watch for file changes
• yarn build-types to generate TS typings.

Installation

The SDK is distributed on npm. To install the SDK and start using it in your client simply run

npm install @messagebird/webrtc

# Or if you use yarn

yarn add @messagebird/webrtc

Initializing an RTC Client

To enable your application to make and receive calls over WebRTC, you have to instantiate a new Device. To connect to the WebRTC server and authenticate with your MessageBird account you need to generate a JWT and pass it to the client Here is an example app that generates a JWT

import { Device } from '@messagebird/webrtc'; // TODO < name

const device = new Device({
  username: 'test',
});

// Open a connection to the MessageBird WebRTC API
device
  .setup({ jwt: 'TEST' })
  .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 Device and opened the connection by calling the .setup() method. After successfully instantiating a new device you can start new RTC connections by calling the connect() method.

device
  .connect({
    // Any additional data can be passed as arguments to the `connect` function
    conference: 'Test conference',
    to: '[phone]',
  })
  .then(connection => {
    // resolves with an `RTCConnection` object (docs)
  })
  .catch(error => {
    // Failed to start a session, error object contains details.
  });

Handling incoming connections

You can handle incoming RTC connections by listening for the the on('incoming') event. (untested)

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

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

Examples

This project comes with an example embedded in the examples directory. To run the example:

• yarn && yarn build -w
• open examples/index.html
• alternatively, change DEFAULT_JWT in examples/index.js for easier debugging
• Example usage in plain JavaScript: https://gitlab.messagebird.io/frontend/javascript-webrtc-sdk/blob/master/examples/index.js
• Example usage in a React app: https://gitlab.messagebird.io/niek/react-webrtc-example

API Reference

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

Device

constructor(options)

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

• username alphanumeric username to identify an agent by name

setup(options)

Connect the Device 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.
• jwt JWT to authenticate.

connect(options)

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

• options An object containing a key<>value mapping of additional string data to be passed along to the connection
• returns a promise that resolves with an connection when the call is connected. Rejects if starting the connection failed.

destroy()

Disconnects all ongoing connections and terminates the connection to the server. After calling destroy, you are required to call setup again before you can start accepting new incoming connections

events

on('ready', handler)

When the device is ready to start receiving and making calls. Can be called multiple times in case the client disconnects and automatically reconnects.

on('offline', handler)

When the device 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 connection object.

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

on('connected', handler)

Fired when a connection is opened, the handler function receives a Connection object as an argument

on('confirmed', handler)

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

on('disconnected', handler)

Fired when a connection disconnects.

Connection

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

disconnect()

Disconnects the device from the connection

Events

IncomingConnection

IncomingConnection extends everything from Connection, but has some additional methods

acccept()

Accept an incomingConnection to start a call.