RELAY Client

Relay client is the basic connection to RELAY, allowing you send commands to RELAY and setup handlers for inbound events.

Constructor

Constructs a client object to interact with RELAY.

Parameters

Examples

Create a Client to interact with the RELAY API.

1
const client = new Relay({
2
  project: 'my-project-id',
3
  token: 'my-jwt',
4
})
5
6
client.on('signalwire.ready', (client) => {
7
  // You are connected with Relay!
8
})
9
10
client.connect()

Properties

Devices and Media Constraints

You can configure the devices your client will use by default with these properties and methods:

Examples

If present, use the first audio output device as default speaker.

1
const speakerList = client.audioOutDevices.toArray()
2
if (speakerList.length) {
3
  client.speaker = speakerList[0].deviceId
4
}

Local and Remote Elements

It is usual, in a WebRTC application, to display the local and remote videos in a video-call. In the case of an audio-only call you will need at least the audio element to play the media.

Note: the client will attach the streams to the proper element but will not change the style attribute. You can decide if you would like to display or hide the HTMLMediaElement following the application logic.
Use the callUpdate notification to detect call state changes and update the UI accordingly.

STUN/TURN Servers

Through the iceServers you can set/retrieve the default ICE server configuration for all subsequent calls.

Examples

Use both STUN and TURN for the client.

1
client.iceServers = [
2
  {
3
    urls: 'stun:stun.example.domain.com'
4
  },
5
  {
6
    urls: 'turn:turn.example.domain.com',
7
    username: '<turn-username>',
8
    credential: '<turn-password>'
9
  }
10
]

Methods

checkPermissions

The first time a user visits your page, before access his microphone or webcam, the browser display a notification to the user. Use this method if you want to check you already have the permission to access them.

Parameters

Returns

Promise<boolean> - A Promise object resolved with a boolean value.

Examples

Check both audio and video permissions.

1
// within an async function ..
2
const success = await client.checkPermissions()
3
if (success) {
4
  // User gave the permission..
5
} else {
6
  // User didn't gave the permission..
7
}

connect

Activates the connection to RELAY. Make sure you have attached the listeners you need before connecting the client, or you might miss some events.

Returns

Promise<void>

Examples

1
await client.connect()

disconnect

Disconnect the client from RELAY.

Returns

void

Examples

1
client.disconnect()

disableMicrophone

Disable the use of the microphone for the subsequent calls.

disableWebcam

Disable the use of the webcam for the subsequent calls.

enableMicrophone

Enable the use of the microphone for the subsequent calls.

enableWebcam

Enable the use of the webcam for the subsequent calls.

getAudioInDevices

Return all audioinput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List microphones.

1
// within an async function ..
2
const devices = await client.getAudioInDevices()
3
devices.forEach(device => {
4
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
5
})

getAudioOutDevices

Return all audiooutput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List speakers.

1
// within an async function ..
2
const devices = await client.getAudioOutDevices()
3
devices.forEach(device => {
4
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
5
})

getDeviceResolutions

Return a list of supported resolutions for the given webcam (deviceId).

Parameters

Returns

Promise<Array> - A Promise object resolved with a list of supported resolutions.

Examples

Check both audio and video permissions.

1
// within an async function ..
2
const resolutions = await client.getDeviceResolutions('d346d0f78627e3b808cdf0c2bc0b25b4539848ecf852ff03df5ac7545f4f5398')
3
4
[
5
  {
6
    "resolution": "320x240",
7
    "width": 320,
8
    "height": 240
9
  },
10
  {
11
    "resolution": "640x360",
12
    "width": 640,
13
    "height": 360
14
  },
15
  {
16
    "resolution": "640x480",
17
    "width": 640,
18
    "height": 480
19
  },
20
  {
21
    "resolution": "1280x720",
22
    "width": 1280,
23
    "height": 720
24
  }
25
]

getDevices

Return all devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List all devices.

1
// within an async function ..
2
const devices = await client.getDevices()
3
devices.forEach(device => {
4
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
5
})

getVideoDevices

Return all videoinput devices supported by the browser.

Parameters

None

Returns

Promise<MediaDeviceInfo[]> - A Promise object resolved with a list of MediaDeviceInfo.

Examples

List webcams.

1
// within an async function ..
2
const devices = await client.getVideoDevices()
3
devices.forEach(device => {
4
  console.log(device.kind + ': ' + device.label + ' id: ' + device.deviceId);
5
})

newCall

Make a new outbound call.

Parameters

Returns

Promise<Call> - A Promise fulfilled with the new outbound Call object or rejected with the error.

Examples

Make an outbound call to +1 202-555-0122 using default values from the Client.

1
// within an async function ..
2
const options = { destinationNumber: '+12025550122' }
3
const call = await client.newCall(options).catch(console.error)

on

Attach an event handler for a specific type of event.

Parameters

Returns

Relay - The client object itself.

Examples

Subscribe to the signalwire.ready and signalwire.error events.

1
client.on('signalwire.ready', (client) => {
2
  // Your client is ready!
3
}).on('signalwire.error', (error) => {
4
  // Got an error...
5
})

off

Remove an event handler that were attached with .on(). If no handler parameter is passed, all listeners for that event will be removed.

Parameters

Returns

Relay - The client object itself.

Examples

Subscribe to the signalwire.error and then, remove the event handler.

1
const errorHandler = (error) => {
2
  // Log the error..
3
}
4
5
client.on('signalwire.error', errorHandler)
6
7
// .. later
8
client.off('signalwire.error', errorHandler)

refreshDevices

DEPRECATED: Use getDevices instead.

Refresh the devices and return a Promise fulfilled with the new devices.

Parameters

None

Returns

Promise<devices> - New devices object.

Examples

Refresh client’s devices with async/await syntax.

1
// within an async function
2
const devices = await client.refreshDevices()

refreshToken

When the JWT is going to expire, the Client dispatch a notification with type refreshToken that allows you to refresh the token and keep your session alive.

Parameters

Returns

Promise<void>

Examples

Listen for all notifications and, on refreshToken, fetch a new JWT from your backend and update the token on the client.

1
client.on('signalwire.notification', function(notification) {
2
  switch (notification.type) {
3
4
    case 'refreshToken':
5
      // Take a new token from your server...
6
      xhrRequestToRefreshYourJWT().then(async (newToken) => {
7
        await client.refreshToken(newToken).catch(console.error)
8
      })
9
    break
10
11
  }
12
})

setAudioSettings

You can set the default audio constraints for your client. See here for further details.

Note: It’s a common behaviour, in WebRTC applications, to persist devices user’s selection to then reuse them across visits.
Due to a Webkit’s security protocols, Safari generates random deviceId on each page load.
To avoid this issue you can specify two additional properties (micId and micLabel) in the constraints input parameter.
The client will use these values to assure the microphone you want to use is available by matching both id and label with the device list retrieved from the browser.

Parameters

Returns

Promise<MediaTrackConstraints> - Audio constraints applied to the client.

Examples

Set microphone by id and label with the echoCancellation flag turned off.

1
// within an async function
2
const constraints = await client.setAudioSettings({
3
  micId: '229d4c8838a2781e3668eb173fea2622b34fbf6a9deec19ee5caeb0916839520',
4
  micLabel: 'Internal Microphone (Built-in)',
5
  echoCancellation: false
6
})

setVideoSettings

You can set the default video constraints for your client. See here for further details.

Note: It’s a common behaviour, in WebRTC applications, to persist devices user’s selection to then reuse them across visits.
Due to a Webkit’s security protocols, Safari generates random deviceId on each page load.
To avoid this issue you can specify two additional properties (camId and camLabel) in the constraints input parameter.
The client will use these values to assure the webcam you want to use is available by matching both id and label with the device list retrieved from the browser.

Parameters

Returns

Promise<MediaTrackConstraints> - Video constraints applied to the client.

Examples

Set webcam by id and label with 720p resolution.

1
// within an async function
2
const constraints = await client.setVideoSettings({
3
  camId: '229d4c8838a2781e3668eb173fea2622b34fbf6a9deec19ee5caeb0916839520',
4
  camLabel: 'Internal Webcam (Built-in)',
5
  width: 1080,
6
  height: 720
7
})

Events

All available events you can attach a listener on.