React WebRTC Adapter

React HOC that binds the Teravoz WebRTC Library to your component props.

Have Teravoz WebRTC bound to wherever you want.

1import React, { Component } from 'react';
2import teravozWebRTCAdapter from '@teravoz/react-webrtc-adapter';
3
4class MyComponent extends Component {
5
6  render() {
7    this.props.teravoz.*
8    ...
9  }
10}
11
12exports default teravozWebRTCAdapter(MyComponent, {
13  apiKey: '<your-api-key>'
14});

Installation

This is a React module that wraps the Teravoz WebRTC adapter and is available through the npm.

Installation is done with npm install or yarn add:

1npm install --save @teravoz/react-webrtc-adapter
2# or
3yarn add @teravoz/react-webrtc-adapter

Initialization Options

• apiKey (Required) - initializes the Teravoz WebRTC pipe (generate you Teravoz api key here).
• loadingComponent - component that will be rendered when loading the Teravoz WebRTC dependencies.
• errorComponent - component that will be rendered when an error occurs.

Methods

There are several methods that enables the communication capabilities. Below you can find all the methods provided by the Teravoz Library to register a peer and make/receive calls. For detailed information, see the Methods Reference.

Registering

• register
• unregister

General

• dial
• hold
• unhold
• mute
• unmute
• hangUp
• sendDTMF

Methods Reference

register

1this.props.teravoz.register('101', '***');

The register('username', 'password') method is required to initialize a session with the Teravoz platform.

• username (string, required) - your peer username (usually the number)
• password (string, required) - your peer password

The register method emits the registering/registered/registrationFailed events. Once the registered is emitted, you are able to make and receive calls.

unregister

1this.props.teravoz.unregister();

The unregister() method must be used when a user/peer needs to be unregistered.

dial

1this.props.teravoz.dial('011987654321');

The dial('number') method must be used to start a call.

• number (string, required) - the number who will be called

hold

1this.props.teravoz.hold();

The hold() method put an ongoing call in a holding state.

unhold

1this.props.teravoz.unhold();

The unhold() method recovers a holded call to an ongoing state.

mute

1this.props.teravoz.mute();

The mute() method mute an ongoing call.

unmute

1this.props.teravoz.unmute();

The unmute() method unmute an ongoing call.

hangUp

1this.props.teravoz.hangUp();

The hangUp() method hang up an ongoing call.

sendDTMF

1this.props.teravoz.sendDTMF('3', { 
2  duration: 500, 
3  gap: 50
4});

The sendDTMF('tone', options = { duration, gap }) method sends a tone.

• tone (char) - the tone to be sent
• options (object, optional) - the DTMF options to send the tone.
  • duration (int, default = 500) - the tone sound duration in milliseconds
  • gap (int, default = 50) - the gap between the tones in milliseconds

Events

There are several events received by the Teravoz WebRTC Adapter during a session. For detailed information, see the Events Reference.

Registering

These events are received when a registration is requested.

• registering
• registered
• registrationFailed
• unregistering
• unregistered

Incoming Call

• incomingCall
• acceptedCall
• isReceivingMedia
• DTMF
• hangUp
• missedCall
• cleanUp

Outgoing Call

• calling
• earlyMedia
• isReceivingMedia
• DTMF
• hangingUp
• hangUp
• cleanUp

WebRTC

• webRTCState

Events Reference

To receive and manage all events indiscriminately, use the * operator:

1this.props.teravoz.events.on('*', (type, payload) => {
2  switch(type) {
3    case 'registering': 
4    case 'registered': 
5    ...
6  }  
7});

on registering

1this.props.teravoz.events.on('registering', () => { ... });

The registering event is received when the register method is called.

on registered

1this.props.teravoz.events.on('registered', () => { ... });

The registered event is received once the peer is succesfull registered (username and password are valid).

on registrationFailed

1this.props.teravoz.events.on('registrationFailed', () => { ... });

The registrationFailed event is received when the username and password are not valid.

on unregistering

1this.props.teravoz.events.on('unregistering', () => { ... });

The unregistering event is received when the unregister() method is called.

on unregistered

1this.props.teravoz.events.on('unregistered', () => { ... });

The unregistered event is received once the peer is succesfull unregistered.

on incomingCall

1this.props.teravoz.events.on('incomingCall', (theirNumber, actions) => { 
2  console.info('Receiving and accepting call from', theirNumber);
3  actions.accept(); // accepts the incoming call
4  // or 
5  actions.decline(); // declines the incoming call
6});

The incomingCall event is received when an incoming call is received. It receives two arguments in the callback:

• theirNumber (string) - the number who is calling
• actions (object) - a call management actions object
  • accept (function) - accepts the current incoming call
  • decline (function) - declines the current incoming call

on acceptedCall

1this.props.teravoz.events.on('acceptedCall', (theirNumber) => { ... });

The acceptedCall event is received when a call is accepted by the incomingCall's actions. It receives one argument in the callback:

• theirNumber (string) - the number who called

on isReceivingMedia

1this.props.teravoz.events.on('isReceivingMedia', (mediaType, on)) => { ... });

The isReceivingMedia event is received once the connection is established between the sides. It receives two arguments in the callback:

• mediaType (string) - the value audio
• on (boolean) - if the media is being transfered

on DTMF

1this.props.teravoz.events.on('DTMF', () => { ... });

The DTMF event is received when additional information is requested.

on hangingUp

1this.props.teravoz.events.on('hangingUp', () => { ... });

The hangingUp event is received once a call is succesfully hanged up.

on hangUp

1this.props.teravoz.events.on('hangUp', () => { ... });

The hangUp event is received when the hangUp() method is called.

on missedCall

1this.props.teravoz.events.on('missedCall', (theirNumber) => { ... });

The missedCall event is received when you received a call but did not answered. It receives one argument in the callback:

• theirNumber (string) - the number who called

on cleanUp

1this.props.teravoz.events.on('cleanUp', () => { ... });

The cleanUp event is received everytime a call lifecycle ends.

on calling

1this.props.teravoz.events.on('calling', () => { ... });

The calling event is received when the dial() method is called.

PS: when the calling event is received the call is not actually ringing yet. In other words, the call did not reach the carrier yet. This event refers to an intermediate state between the dial and the ringing states of a call. In this point you should consider using some fake audio to simulate the ringing.

on earlyMedia

1this.props.teravoz.events.on('earlyMedia', (theirNumber) => { ... });

The earlyMedia event is received when a connection is in fact established, even if the call goes to the voicemail.. It receives one argument in the callback:

• theirNumber (string) - the number who is calling

on webRTCState

1this.props.teravoz.events.on('webRTCState', (on) => { ... });

The webRTCState event is received when there is a change in the WebRTC state. It receive one argument in the callback:

• on (boolean) - if the WebRTC is on

Roadmap

• Full test coverage
• v1 Release