RingCentral WebPhone Library

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

Table of Contents

1. Installation
2. Usage
3. Configuring your RingCentral app
4. Include Library And HTML Elements
5. Application
6. API
7. Initiating The Call
8. Accepting Incoming Call
9. DTMF
10. Hold Unhold
11. Mute Unmute
12. Park
13. Flip
14. Transfer
15. Forward
16. Start Stop Recording
17. Barge Whisper
18. Development
19. Demo app
20. Demo app structure

---

Installation

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

---

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 , Interoperability	Specific application permission required
Platform type	Browser-based	Client edition is not compatible with current Brand

You need to have a DIGITAL LINE attached to an extension. You can configure this in Online Web Portal Production , Sandbox

These can be configured for your app in the RingCentral Developer Portal. Fill this Registration Form to get access to WebRTC permissions. Please contact [email protected] 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=".../ringcentral-bundle.js" type="text/javascript"></script>
<script src=".../ringcentral-web-phone.js" type="text/javascript"></script>

Application

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 platform = sdk.platform();

platform
    .login({
        username: '...',
        password: '...'
    })
    .then(function(loginResponse) {
    
        return platform
            .post('/client-info/sip-provision', {
                sipInfo: [{transport: 'WSS'}]
            })
            .then(function(res) {
            
                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
                    }
                });
                
            });
        
    })
    .then(function(webPhone){
    
        // YOUR CODE HERE
    
    })
    .catch(function(e){
        console.error(e.stack);
    });

---

API

Except for some RingCentral-specific features the API is 100% the same as SIP.JS: http://sipjs.com/api/0.7.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

Initiating The Call

var session = webPhone.userAgent.invite('PHONE_NUMBER', {
    media: {
        render: {
            remote: document.getElementById('remoteVideo'),
            local: document.getElementById('localVideo')
        }
    },
    fromNumber: 'PHONE_NUMBER', // Optional, Company Number will be used as default
    homeCountryId: '1' // Optional, the value of
}).then(...);

Accepting Incoming Call

webPhone.userAgent.on('invite', function(session){
    session.accept({
        media: {
            render: {
                remote: document.getElementById('remoteVideo'),
                local: document.getElementById('localVideo')
            }
        }
    }).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(...);

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.

Development

Demo app

$ git clone https://github.com/ringcentral/ringcentral-web-phone.git
$ npm install
$ npm install bower -g // skip this if you've already installed Bower
$ bower install

WebRTC works with issues when served from file system directly to browser (e.g. file:// protocol), you will need a local HTTP server. If you don't have local HTTP server, please install it as well:

$ sudo npm install http-server -g
$ http-server

1. Open localhost:8080/demo/ in the browser
2. Add your RC credentials and click on Register Sip Configurations .
3. For making outbound calls, enter phone number and click on call. To disconnect to call, click on Disconnect Call.
4. For receiving incoming calls, Click on Accept button when window pops up (will be visible when there is an incoming call).

The demo app uses the sandbox environment. If there's any connection problems, you may need to switch to the production environment.

Functionalities included:

1. Sip Register/UnRegister
2. Make Outgoing Calls
3. Accept Incoming calls
4. Hold/UnHold calls
5. Mute/Unmute calls
6. Transfer calls
7. Record/Stop recording calls
8. Flip, park calls
9. Send DTMF
10. Forward incoming calls

Demo app structure

/src
  /demo
    /img
    favicon.ico
    index.html
    index.js