RingCentral WebPhone Library

The RingCentral WebPhone Library includes a JavaScript WebRTC library and a WebRTC phone demo app.

Prerequisites

You will need an active RingCentral account. Don't have an account? Get your Free RingCentral Developer Account Now!
App type should be either :
- Browser-Based
- Server/Web

Browser Compatibility

Currently, we officially support Google Chrome browser. Official support for Firefox and Safari browsers are coming soon.

Network Requirements

Please visit Network Requirement links below

Condensed Requirements: https://netstorage.ringcentral.com/guides/network_condensed.pdf
Extended Requirements: https://netstorage.ringcentral.com/guides/network_extended.pdf

Installation

npm install ringcentral-web-phone
// or
bower install ringcentral-web-phone

If you are not using Bower or NPM:

Download SIP.JS: https://sipjs.com/download/sip-0.13.5.js
Download WebPhone SDK: https://github.com/ringcentral/ringcentral-web-phone/releases/latest
Download audio files:
1. https://cdn.rawgit.com/ringcentral/ringcentral-web-phone/master/audio/incoming.ogg
2. https://cdn.rawgit.com/ringcentral/ringcentral-web-phone/master/audio/outgoing.ogg

Usage

Configuring your RingCentral app

Ensure your app has the following properties set. If these are not set, the error specified will be returned.

App Property	Value	Error if not set
Permissions	`VoIP Calling`	`Specific application permission required`
Platform type	`Browser-based`	`Client edition is not compatible with current Brand`

Since WebRTC enables dialing out, you need to have a DIGITAL LINE attached to an extension to use this capability. You can configure this in Online Web Portal for Production and Sandbox accounts. More information on Digital Lines and their configuration is available in the following RingCentral Knowledge Base article topics:

Digital Line Overview (KB 5862)
Adding a Digital Line (KB 3136). A limited number of Digital Lines are free with each sandbox account which can be configured with the free RingCentral for Desktop softphone.
Reassigning an Existing Digital Line (KB 3748)

These permissions be configured for your app in the RingCentral Developer Portal. Fill this Registration Form to get access to WebRTC permissions. Please contact devsupport@ringcentral.com to request these permissions.

Include Library And HTML Elements

<video id="remoteVideo" hidden="hidden"></video>
<video id="localVideo" hidden="hidden" muted="muted"></video>

<script src=".../sip.js" type="text/javascript"></script>
<script src=".../ringcentral-web-phone.js" type="text/javascript"></script>

Application

For this example you will also need to have RingCentral JS SDK installed.

Configure the web-phone

var appKey = '...'; 
var appSecret = '...';
var appName = '...';
var appVersion = '...';
 
var sdk = new RingCentral.SDK({
    appKey: appKey,
    appSecret: appSecret,
    appName: appName,
    appVersion: appVersion,
    server: RingCentral.SDK.server.production // or .sandbox
});

var remoteVideoElement =  document.getElementById('remoteVideo');
var localVideoElement  = document.getElementById('localVideo');

var platform = sdk.platform();

platform
    .login({
        username: '...',
        password: '...'
    })
    .then(function(loginResponse) {
    
        return platform
            .post('/client-info/sip-provision', {
                sipInfo: [{transport: 'WSS'}]
            })
            .then(function(res) { // Doing nested then because we need loginResponse in a simple way
            
                return new RingCentral.WebPhone(res.json(), { // optional
                    appKey: appKey,
                    appName: appName,
                    appVersion: appVersion,
                    uuid: loginResponse.json().endpoint_id,
                    logLevel: 1, // error 0, warn 1, log: 2, debug: 3
                    audioHelper: {
                        enabled: true, // enables audio feedback when web phone is ringing or making a call
                        incoming: 'path-to-audio/incoming.ogg', // path to audio file for incoming call
                        outgoing: 'path-to-audio/outgoing.ogg' // path to aduotfile for outgoing call
                    },
                    media:{
                        remote: remoteVideoElement,
                        local: localVideoElement
                    },
                    //to enable QoS Analytics Feature
                    enableQos:true
                });
                
            });
        
    })
    .then(function(webPhone){
    
        // YOUR CODE HERE
    
    })
    .catch(function(e){
        console.error(e.stack);
    });

Demo

$ git clone https://github.com/ringcentral/ringcentral-web-phone.git
$ cd ringcentral-web-phone
$ npm start

Open http://localhost:8080/demo/ in the browser (port may change if 8080 will be already used by other app)
If your Application is of the Scope
Server/Web
Browser-Based
Then you would need to add http://localhost:8080/demo/callback.html as the OAuth Redirect URI for the application in Developer Portal
Add your RC credentials and click on Register
For making outbound calls, enter phone number and click on Call
For receiving incoming calls, Click on Accept button when window pops up (will be visible when there is an incoming call)

If there's any connection problems to Sandbox environment, you may need to switch to the Production environment.

WebRTC works with issues when served from file system directly to browser (e.g. file:// protocol), so you will need a local HTTP server (comes with this package).

Online demo is hosted at http://ringcentral.github.io/ringcentral-web-phone

** NOTE : If you are using the online demo, please add http://ringcentral.github.io/ringcentral-web-phone/callback.html to the app's OAuth Redirect URI

API

Except for some RingCentral-specific features the API is 100% the same as SIP.JS: http://sipjs.com/api/0.13.0: most of the time you will be working with RC-flavored UserAgent and Session objects of SIP.JS.

We encourage you to take a look at Guides section, especially Make A Call and Receive A Call articles.

Constructor

var webPhone = new RingCentral.WebPhone(provisionData, options);

Provision Data — the JSON returned from /client-info/sip-provision API endpoint
Options — object with various configuration options that adjust WebPhone behavior
- appKey — your application key
- appName — your application short code name
- appVersion — your application version
- uuid — manually provide the unique identifier of WebPhone instance (should persist between page reloads)
- logLevel — controls verboseness in browser console
  - 0 — Errors only (good for production)
  - 1 — Errors & warnings
  - 2 — Errors, warnings, logs
  - 3 — Everything including debug information (good for development)
- audioHelper — audio feedback when web phone is ringing or making a call
  - enabled — turns feedback on and off
  - incoming — path to incoming.ogg, audio file for incoming call
  - outgoing — path to outgoing.ogg, audio file for outgoing call
- onSession — this callback will be fired each time User Agent starts working with session (incoming or outgoing)
- enableQos:true — will enable quality of service for webRTC calls , you can view the voice quality of calls in analytics portal

Attaching Media Streams

For futher information, refer SIP.js guide to attach media

Initiating The Call

var session = webPhone.userAgent.invite('PHONE_NUMBER', {
    fromNumber: 'PHONE_NUMBER', // Optional, Company Number will be used as default
    homeCountryId: '1' // Optional, the value of
});

Accepting Incoming Call

webPhone.userAgent.on('invite', function(session){
    session.accept().then(...);
});

DTMF

Callee will be put on hold and the another person can join into the call by dialing the extension number announced within the call.

session.dtmf('DTMF_DIGITS').then(...);

Hold Unhold

Callee will be put on hold and the another person can join into the call by dialing the extension number announced within the call.

session.hold().then(...);
session.unhold().then(...);

Mute Unmute

Callee will be put on mute or unmute

session.mute();
session.unmute();

Park

Callee will be put on hold and the another person can join into the call by dialing the extension number announced within the call.

session.park().then(...);

Flip

Caller can filp calls to different devices logged in through the same credentials.

session.flip('TARGET_NUMBER').then(...);

Transfer

session.transfer('TARGET_NUMBER').then(...);

Warm Transfer

If an agent has an active call with a customer and needs to transfer this call to a supervisor, then agent puts existing call on hold, makes a call to a supervisor and when ready performs a warm transfer. Customer will be connected to supervisor and the call between customer and agent will be disconnected.

Warm transfer puts current line on hold (if not done yet) then takes an existing line from arguments and makes transfer.

session.hold().then(function(){
    
    return new Promise(function(resolve, reject){
            
        var newSession = webPhone.userAgent.invite('PHONE_NUMBER', {
            media: {}
        });
        
        // when ready call the following code, for example when user clicks "Complete Transfer" button
        document.getElementById('complete-transfer').addEventListener('click', function(){
            resolve(session.warmTransfer(newSession));
        });

    });
        
}).then(...).catch(...);

Forward

session.forward('TARGET_NUMBER').then(...);

Start/Stop Recording

session.startRecord().then(...);
session.stopRecord().then(...);

Barge/Whisper

Not yet implemented. Could be done by dialing *83. The account should be enabled for barge/whisper access through system admin.

Upgrade Procedure from v0.4.X to 0.7.2

SDK constructor now allows to add custom UA Configuration parameters like sessionDescriptionHandlerFactory , sessionDescriptionHandlerFactoryOptions
SDK now handles rendering HTML Media Elements. Pass remoteVideo and localVideo elements via SDK constructor
SDK also offers to addTrack() to handle remoteVideo and localVideo elements outside the constructor too
SDK sets sdpSemantics value to plan-b. You can now enable unifiedSDP plan by setting the custom UA configuration option options.enableUnifiedSDP to true
For FireFox browser support
- Client application needs to detect if the browser is firefox.
- Client application needs to set custom UA configuration option 'options.enableMidLinesInSDP' to true for browser >= FF v63 for hold functionality to work
- QoS feature is not supported on FireFox due to browser related bugs. Please set the custom UA configuration option options.enableQos to false

Initialization

Before:

webPhone = new RingCentral.WebPhone(data, {
            appKey: localStorage.getItem('webPhoneAppKey'),
            audioHelper: {
                enabled: true
            },
            logLevel: parseInt(logLevel, 10),
            appName: 'WebPhoneDemo',
            appVersion: '1.0.0',
        });

After:

var remoteVideoElement =  document.getElementById('remoteVideo');
var localVideoElement  = document.getElementById('localVideo');
webPhone = new RingCentral.WebPhone(data, {
    appKey: localStorage.getItem('webPhoneAppKey'),
    audioHelper: {
        enabled: true
    },
    logLevel: parseInt(logLevel, 10),
    appName: 'WebPhoneDemo',
    appVersion: '1.0.0',
    media: {
        remote: remoteVideoElement,
        local: localVideoElement
    },
    //to enable QoS Analytics Feature  
    enableQos:true
});

Accept Invites:

Before:

var acceptOptions = {	
            media: {	
                render: {	
                    remote: document.getElementById('remoteVideo'),	
                    local: document.getElementById('localVideo')	
                }	
            }	
      };
...
...
session.accept(acceptOptions).then(function() {
...    
});;

After:

session.accept().then(function() {
...    
})

Send Invite:

Before:

var session = webPhone.userAgent.invite(number, {
    media: {
        render: {
            remote: document.getElementById('remoteVideo'),
            local: document.getElementById('localVideo')
        }
    },
    fromNumber: username,
    homeCountryId: homeCountryId
});

After:

var session = webPhone.userAgent.invite(number, {
    fromNumber: username,
    homeCountryId: homeCountryId
});

Compatibility Matrix

Date	SDK	SIPJS	Chrome	Firefox
Feb 2016	0.2.0	0.6.4	not known may be v50-70	⚠️ NA
Apr 2016	0.3.0	0.7.3	not known may be v50-70	⚠️ NA
Jun 2016	0.3.1	0.7.4	not known may be v50-70	⚠️ NA
Aug 2016	0.3.2	0.7.5	54 to 56	⚠️ NA
Sep 2016	0.4.0-RC1	0.7.5	54 to 56	⚠️ NA
Jan 2017	0.4.0	0.7.5	54 to 56	⚠️ NA
Mar 2017	0.4.1	0.7.7	54 to 70, rtcp mux support, media API changes	⚠️ Issues with Audio, SBC
Aug 2017	0.4.2	0.7.7	61 to 70	⚠️ Issues with Audio, SBC
Aug 2017	0.4.3	0.7.8	61 to 70	⚠️ Not Tested
Sep 2017	0.4.4	0.7.8	62 to 70	⚠️ Issues with DTMF
Nov 2017	0.4.5	0.7.8	64 to 70	⚠️ Issues with DTMF
Jul 2018	0.5.0	0.10.0	68 to 70	⚠️ Issues with DTMF
Nov 2018	0.6.0	0.11.3	68 to 70	Regression tested for 62, 63 supported with custom modifiers
Nov 2018	0.6.1	0.11.6	71+, explicit `plan b` SDP support	62 to 64
Dec 2018	0.6.2	0.11.6	71+	62 to 65
Feb 2019	0.6.3	0.11.6	71+	62 to 65 , ⚠️ QoS feature not supported
Apr 2019	0.7.0	0.13.5	71+	62 to 65 , ⚠️ QoS feature not supported
May 2019	0.7.1	0.13.5	71+	62 to 65 , ⚠️ QoS feature not supported
Jun 2019	0.7.2	0.13.5	71+	62 to 65 , ⚠️ QoS feature not supported

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

RingCentral WebPhone Library

Prerequisites

Browser Compatibility

Network Requirements

Table of Contents

Installation

If you are not using Bower or NPM:

Usage

Configuring your RingCentral app

Include Library And HTML Elements

Application

Demo

API

Constructor

Attaching Media Streams

Initiating The Call

Accepting Incoming Call

DTMF

Hold Unhold

Mute Unmute

Park

Flip

Transfer

Warm Transfer

Forward

Start/Stop Recording

Barge/Whisper

Upgrade Procedure from v0.4.X to 0.7.2

Initialization

Accept Invites:

Send Invite:

Compatibility Matrix

Files

README.md

Latest commit

History

README.md

File metadata and controls

RingCentral WebPhone Library

Prerequisites

Browser Compatibility

Network Requirements

Table of Contents

Installation

If you are not using Bower or NPM:

Usage

Configuring your RingCentral app

Include Library And HTML Elements

Application

Demo

API

Constructor

Attaching Media Streams

Initiating The Call

Accepting Incoming Call

DTMF

Hold Unhold

Mute Unmute

Park

Flip

Transfer

Warm Transfer

Forward

Start/Stop Recording

Barge/Whisper

Upgrade Procedure from v0.4.X to 0.7.2

Initialization

Accept Invites:

Send Invite:

Compatibility Matrix