Tutorials>Getting Started with WebRTC

This tutorial will help developers understand the basics of using RingCentral WebRTC and the Web Phone Client Library using JavaScript. Click the "Start" button below to begin.

Start Tutorial

Welcome to the Getting Started with RingCentral WebRTC Tutorial

WebRTC is a powerful communication tool available for developers which provides the capability implement WebRTC for making and receiving calls directly within their web applications.

Most common use cases for WebRTC

  • SaaS - Call Telephony Integrations
  • CRM - Click to Dial

Requirements

Using the Demo

Please follow the directions in the README.md file under the Demo section to use the WebRTC Web Phone Demo app either locally or using the hosted Web Phone Demo App on Heroku

Using Bower

npm install ringcentral-web-phone

Using NPM

npm install ringcentral-web-phone

Using Vanilla JS

  1. Download SIP.JS: http://sipjs.com/download/sip-0.7.5.js
  2. Download WebPhone SDK: https://cdn.rawgit.com/ringcentral/ringcentral-web-phone/master/src/ringcentral-web-phone.js
  3. 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

Now, let's take a look at the code behind the Demo to become familiar with developing RingCentral WebRTC application integrations, demo/index.html.

Required Markup

Since WebRTC is browser-based, you will need to include two HTML5 video tags with some specific properties in your markup to operate the RingCentral Web Phone.

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

Vendor Resources

Additionally, the demo references some external JavaScript files. The following of which are required for the RingCentral Web Phone to operate. Please note that the src attributes for your application may differ depending upon your method of installation and where you install your vendor libraries.

  • jQuery
  • Bootstrap (optional, but helpful)
  • Fetch
  • ES6-Promise
  • PubNub
  • SIP.js
  • RingCentral JS SDK
  • RingCentral Web Phone
  • Your Application Code (index.js)

Next we will take a look at the templatized markup used to load various views of the Web Phone Demo.m

Incoming Call UI

This template is used when the application code receives an incoming voice call.

Make a Call UI

When users have successfully authenticated with the demo application, this is the default UI displayed and is used for placing outbound voice calls using WebRTC.

Login UI

When the demo application has initially loaded, and the user has not authenticated, this UI is displayed which supports using Password Flow Authentication (which actually should not be used with browser-based applications).

Active Call UI

When a call has been placed (outbound) or received (inbound), and successfully accepted, this is the template UI which will be displayed to the user. In it, are all the primary operations of the Web Phone:

  • Volume + / -
  • Mute / Unmute
  • Hold / Unhold
  • Start / Stop Recording
  • Transfer
  • Park
  • Flip
  • Send DTMF Tone

Index.js

Since WebRTC is browser-based, your application code to operate the RingCentral Web Phone will be written in JavaScript. This file is referenced (after all other dependencies) in your markup.

Application Variables

We begin by setting up application variables which are required, and caching some jQuery selectors for simplified reference.

Template Loader

This function handles loading the templates of the demo. This is not a recommended pattern for production applications, since it introduces some potential memory leaks with any event bindings, but as this is a demo app...we do not mind as much.

Obtain RingCentral API Token

Here we are using the RingCentral JavaScript SDK to login to RingCentral and obtain a valid API token. You will want to replace this with an Authorization Flow (3-legged OAuth) implementation if you are using this code in a SaaS or "multi-tenant" application.

Once we have this data, we cache it in Local Storage of the browser, and lastly we retrieve information about the extension which has just authenticated.

SIP Provisioning

Once we have received the information about the currently authenticated extension, we attempt to provision SIP (which is used to determine if we are able to register as a WebRTC user for making and receiving calls over WebRTC).

SIP Registration

Once we have successfully received the client information and provisioned SIP, we pass the SIP provisioning response to our register function which is responsible for creating the Web Phone and User Agent instances as well as registering event handlers on the User Agent object for the following events:

  • Invite
  • Connecting
  • Connected
  • Disconnected
  • Registered
  • Unregistered
  • RegistrationFailed
  • Message

Then the Web Phone object is returned to the register method caller.

Load the Make Call Form

Once we have successfully registered and created the Web Phone, the promise chain calls the makeCallForm function which loads the appropriate UI template (Make Call Form) and registers an eventHandler to store the last dialed number, and which then executes the makeCall method (that actually uses the Web Phone to place the outbound voice call using WebRTC).

Making the Call

The makeCall method expects a phone number and home country id to be passed.

This method defines a new session which is the result of executing the Web Phone's User Agent's invite method.

The invite method of the User Agent expects to be provided:

  • number (str): the target phone number to dial in e.164 format
  • config object with the following properites:
    • media (obj): which renders the required HTML we created earlier
    • fromNumber (str): the currently authenticated user's phone number in e.164 format
    • homeCountryId

Then the onAccepted method is called with the session (result of calling the User Agent's invite method) in the previous step.

Accepted Calls

This is one of the longest methods in the application (depending upon the types of functionalities you desire in your Web Phone application integrations). Since we include every operation available on the Web Phone, you can see the complete reference of how we handle each of these events here from both a UI and session perspective.

It is important to note that the onAccepted method is used for both inbound and outbound voice calls in the demo, but you may have differing use cases and requirements that demand a different architecture.

Also, you will see that all operations are performed on the session object while you are using the Web Phone library, but by using this resource your integration code can be simplified considerably.