2.x version is a complete rewrite and it has tons of improvements. It's hosted on main branch:
- 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
Currently, we officially support Google Chrome browser. Other browsers may work as well but they are not tested.
Please visit Network Requirement links below
- Network Requirements and Recommendations | RingCentral Office : https://support.ringcentral.com/s/article/9233?language=en_US
- Network Requirements and Recommendations - Resources : https://support.ringcentral.com/s/article/Network-Requirements-and-Recommendations-Resources?language=en_US
Here is a demo application based on React.js: https://chuntaoliu.com/rc-web-phone-demo/
Source code is here: https://github.com/tylerlong/rc-web-phone-demo
- Installation
- Usage
- Configuring your RingCentral app
- Include Library And HTML Elements
- Application
- Demo
- API
- Initiating The Call
- Accepting Incoming Call
- DTMF
- Hold Unhold
- Mute Unmute
- Park
- Flip
- Transfer
- Warm Transfer
- Forward
- Start/Stop Recording
- Barge/Whisper
yarn add ringcentral-web-phone
Or you may referece it in html directly:
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/index.umd.js"></script>You may need to replace 1.0.8 with latest version number. For latest version please check here: https://www.npmjs.com/package/ringcentral-web-phone?activeTab=versions
Please also note that: 2.x and 1.x are not compatible. You will to read 2.x README file if you want to use 2.x version instead.
Please note that, SIP.js has been bundled into index.umd.js so you don't need to reference it separately.
Download audio files:
- https://cdn.rawgit.com/ringcentral/ringcentral-web-phone/master/demo/audio/incoming.ogg
- https://cdn.rawgit.com/ringcentral/ringcentral-web-phone/master/demo/audio/outgoing.ogg
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 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).
- 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 [email protected] to request these permissions.
<video id="remoteVideo" hidden="hidden"></video> <video id="localVideo" hidden="hidden" muted="muted"></video>For this example you will also need to have RingCentral JS SDK installed.
Configure the web-phone
var clientId = '...';
var clientSecret = '...';
var appName = '...';
var appVersion = '...';
var sdk = new RingCentral.SDK({
clientId: clientId,
clientSecret: clientSecret,
appName: appName,
appVersion: appVersion,
server: RingCentral.SDK.server.production,
});
var remoteVideoElement = document.getElementById('remoteVideo');
var localVideoElement = document.getElementById('localVideo');
var platform = sdk.platform();
platform
.login({
jwt: '...',
})
.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
clientId: clientId,
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);
});$ git clone https://github.com/ringcentral/ringcentral-web-phone.git
$ cd ringcentral-web-phone
$ yarn install
$ yarn serve- Open
http://localhost:1234in the browser (port may change if1234will be already used by other app) - If your Application is of the Scope
Server/WebBrowser-BasedThen you would need to addhttp://localhost:1234/callback.htmlas 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
Acceptbutton when window pops up (will be visible when there is an incoming call)
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 https://ringcentral.github.io/web-phone-demo-1/
** NOTE : If you are using the online demo, please add
https://ringcentral.github.io/web-phone-demo-1/callback.html to the app's
OAuth Redirect URI
Except for some RingCentral-specific features the API is 100% the same as SIP.JS: 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.
var webPhone = new RingCentral.WebPhone(provisionData, options);- Provision Data — the JSON returned from
/client-info/sip-provisionAPI endpoint - Options — object with various configuration options that adjust WebPhone
behavior
clientId— your application keyappName— your application short code nameappVersion— your application versionuuid— manually provide the unique identifier of WebPhone instance (should persist between page reloads)logLevel— controls verboseness in browser console0— Errors only (good for production)1— Errors & warnings2— Errors, warnings, logs3— Everything including debug information (good for development)
audioHelper— audio feedback when web phone is ringing or making a callenabled— turns feedback on and offincoming— path toincoming.ogg, audio file for incoming calloutgoing— path tooutgoing.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
For futher information, refer SIP.js guide to attach media
var session = webPhone.userAgent.invite('PHONE_NUMBER', {
fromNumber: 'PHONE_NUMBER', // Optional, Company Number will be used as default
homeCountryId: '1', // Optional, the value of
});webPhone.userAgent.on('invite', function(session){
session.accept().then(...);
});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(...);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(...);Callee will be put on mute or unmute
session.mute();
session.unmute();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(...);Caller can filp calls to different devices logged in through the same credentials.
session.flip('TARGET_NUMBER').then(...);session.transfer('TARGET_NUMBER').then(...);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.
Steps:
- Put the current session on
Holdas shown in the demo code - Initiate a new session (Start new call)
- a. Once new call is answered ,
Completethe transfer , or terminate new session. b. If you want to switch to original call, switch the session context andUnholdthe session
$modal.find('.transfer-form button.warm').on('click', function (e) {
session.hold().then(function () {
console.log('Placing the call on hold, initiating attended transfer');
var newSession = session.userAgent.invite($transfer.val().trim());
newSession.once('established', function () {
console.log('New call initated. Click Complete to complete the transfer');
$modal.find('.transfer-form button.complete').on('click', function (e) {
session
.warmTransfer(newSession)
.then(function () {
console.log('Warm transfer completed');
})
.catch(function (e) {
console.error('Transfer failed', e.stack || e);
});
});
});
});
});session.forward('TARGET_NUMBER').then(...);sesstion.reject() method has been available since long ago. It will send a SIP
"480 Temporarily Unavailable" message to SIP server. I believe this method is
from SIP.js since I don't see any relavent code in this repo. There is a
potential issue with this methods, sometimes server side will re-send the invite
message to you. Not always reproducible but quite annoying. The call will appear
again right after you "reject".
session.decline() method was added in 1.0.5. It sends a special XML message to
SIP server to ignore the call. And RingCentral SIP servers understand this
message and will not bother you again about this call session.
session.startRecord().then(...);
session.stopRecord().then(...);There is a special case that call recording is auto started by server side: #292
Not yet implemented. Could be done by dialing *83. The account should be enabled for barge/whisper access through system admin.
Before:
webPhone = new RingCentral.WebPhone(data, {
clientId: localStorage.getItem('webPhoneClientId'),
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, {
clientId: localStorage.getItem('webPhoneClientId'),
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,
//to enable media stats logging
enableMediaReportLogging: true,
});Before:
var acceptOptions = {
media: {
render: {
remote: document.getElementById('remoteVideo'),
local: document.getElementById('localVideo')
}
}
};
...
...
session.accept(acceptOptions).then(function() {
...
});;After:
session.accept().then(function() {
...
})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,
});For incoming calls
function onInvite(session) {
if (session.request.headers['Alert-Info'][0].raw === 'Auto Answer') {
session
.accept()
.then(function() {
onAccepted(session);
})
.catch(function(e) {
console.error('Accept failed', e.stack || e);
});
}
...
...
}| Date | SDK | SIPJS | Chrome | Firefox |
|---|---|---|---|---|
| Feb 2016 | 0.2.0 | 0.6.4 | not known may be v50-70 | |
| Apr 2016 | 0.3.0 | 0.7.3 | not known may be v50-70 | |
| Jun 2016 | 0.3.1 | 0.7.4 | not known may be v50-70 | |
| Aug 2016 | 0.3.2 | 0.7.5 | 54 to 56 | |
| Sep 2016 | 0.4.0-RC1 | 0.7.5 | 54 to 56 | |
| Jan 2017 | 0.4.0 | 0.7.5 | 54 to 56 | |
| Mar 2017 | 0.4.1 | 0.7.7 | 54 to 70, rtcp mux support, media API changes | |
| Aug 2017 | 0.4.2 | 0.7.7 | 61 to 70 | |
| Aug 2017 | 0.4.3 | 0.7.8 | 61 to 70 | |
| Sep 2017 | 0.4.4 | 0.7.8 | 62 to 70 | |
| Nov 2017 | 0.4.5 | 0.7.8 | 64 to 70 | |
| Jul 2018 | 0.5.0 | 0.10.0 | 68 to 70 | |
| 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 , |
| Apr 2019 | 0.7.0 | 0.13.5 | 71+ | 62 to 65 , |
| May 2019 | 0.7.1 | 0.13.5 | 71+ | 62 to 65 , |
| Jun 2019 | 0.7.2 | 0.13.5 | 71+ | 62 to 65 , |
| Nov 2019 | 0.7.3 | 0.13.5 | 71+ | 62 to 65 , |
| Nov 2019 | 0.7.5 | 0.13.5 | 71+ | 62 to 65 , |
| Jan 2020 | 0.7.6 | 0.13.5 | 71+ | 62 to 65 , |
| Jan 2020 | 0.7.7 | 0.13.5 | 71+ | 62 to 65 , |
| Feb 2020 | 0.7.8 | 0.13.5 | 71+ | 62 to 65 , |
| Mar 2020 | 0.8.0 | 0.13.5 | 71+ | 62 to 65 , |
| May 2020 | 0.8.1 | 0.13.5 | 71+ | 62 to 65 , |
| Jul 2020 | 0.8.2 | 0.13.5 | 71+ | 62 to 65 , |
| Oct 2020 | 0.8.3 | 0.13.5 | 71+ | 62 to 65 , |
| Dec 2020 | 0.8.4 | 0.13.5 | 71+ | 62 to 65 , |
| Feb 2021 | 0.8.5 | 0.13.5 | 71+ | 62 to 65 , |
