Phone calls in your web browser with Bandwidth and WebRTC

November 23, 2015

DISCLAIMER: This blog post contains legacy content. As of June 2019, Bandwidth currently does not support WebRTC, but we are working on reinstating compatibility. Be on the lookout in early 2020 for updates.

What is WebRTC?

WebRTC is a free, open project that provides browsers and mobile applications with Real-Time Communications (RTC) capabilities via simple APIs. The WebRTC components have been optimized to best serve this purpose.

Essentially, WebRTC allows two people to communicate in real time over the internet, typically via a web browser (think google hangouts).

How is Bandwidth Involved?

Bandwidth provides a communications API which allows users to create and manage SIP endpoints.

Furthermore, Bandwidth provides an SDK via github that ties directly into the communication API.

Putting it all together

There are four basic steps:

Configure a SIP endpoint with Bandwidth.
Configure and deploy one of the SIP Calling App Servers to handle the outgoing and incoming calls
Obtain an authorization token to make and receive calls
Use BWClient WebRTC JavaScript Library with authorization token to connect to Bandwidth to make and receive calls

Creating a SIP endpoint with Bandwidth

Prerequisites:

Create an /applications resource, set your incomingCallUrl to your server with auto-answer = false
Configure an incoming phone number associated with your application
Your account is enabled for domains. Contact Bandwidth Support to enable your account

Create a unique domain for your service to use

A domain is a way to logically group endpoints. The name of the domain will be part of a public DNS record. For that reason, we let the customer choose their domain names. Once a domain has been created, endpoints can be created and managed within the context of the domain. Because endpoints can only exist within the context of a domain, creating a domain is the first step in creating endpoints.

POST /v1/users/{user-id}/domains 
{
  "name": "xyz-corp-testing",
  "description": "Testing Demo Domain"
}

HTTP/1.1 201 Created 
Location: /v1/users/{user-id}/domains/{domain-id}

Step 2: Create an endpoint/user

An endpoint represents an entity that can register with the Bandwidth App Platform Registrar and place and receive calls. An endpoint is addressable using a unique SIP URI which is constructed using the endpoint’s user name and the domain in which the endpoint exists.

| E.g. user1234@xyz-corp-testing.bwapp.bwsip.io

There are no restrictions on the number of SIP clients that can be associated with an endpoint. That is, an application can create one endpoint in the Bandwidth App Platform and give the SIP URI and credentials to as many of their own clients as it likes. However, when a call is made to the SIP URI for that endpoint, all clients registered as that endpoint (using that SIP URI and credentials to register) will receive the call. The call will be completed to the first client that answers.

If you don’t want all your SIP clients to ring simultaneously, create an endpoint for each client. You can still associate a single phone number with a group of clients, but the application has more control over which client will ring when that number is called.

POST /v1/users/{user-id}/domains/{domain-id}/endpoints 
{
 "name" : "jsmith_mobile", 
 "description" : "John Smiths mobile client", 
 "domain_id" : "{domain-id}", 
 "application_id" : "{application-id}", 
 "enabled" : "true",
 "credentials" : { "password" : "abc123" } 
}

HTTP/1.1 201 Created 
Location: /v1/users/{user-id}/domains/{domain-id}/endpoints/{endpoint-id}

NOTE: You must associate an “application-id” with your endpoint to receive events from your endpoint. See the applications resource for how to create an application id.

Configure and Deploy SIP Calling App Server

In order to make and receive calls from and to the user/endpoint you created above, you need a calling app server to handle outgoing and incoming calls. Bandwidth provides sample app servers for multiple languages. Follow the link below and the instructions to launch the app.

Obtaining Authorization Token

Making and receiving a call in the browser is done through a Bandwidth JavaScript library called BWClient. Using the BWClient library you will login for a given user/endpoint. For security reasons, you do not want the password exposed in the JavaScript code running in the browser.

Therefore, you will obtain an authorization token in your App Server and use that token to login.

To create an authorization token, use the following REST API:

POST /v1/users/<user-id>/domains/<domain-id>/endpoints/<endpoint-id>/tokens
{}

HTTP/1.1 201 Create
Headers:
Location: <host>/v1/users/<user-id>/domains/<domain-id>/endpoints/<endpoint-id>/tokens/<token>

{
  “expires” : 86400,
  “token”: “283ha89bva289fajf2093jf”
}