WebRTC Integration Guide

Introduction

WebRTC Cloud Softphone app is not a classic standalone SIP client like iOS or Android Cloud Softphone apps. WebRTC platform uses several technologies which are not commonly supported by SIP backends. WebRTC doesn’t define any signalization protocols and the nature of web apps make it difficult to use direct TCP or UDP connection to SIP server.

Acrobits has developed several software components which make WebRTC client work with virtually any existing SIP provider. This document gives a brief overview about them and explains their role in the whole client-server infrastructure.

WebRTC specifics

Signalization

WebRTC client doesn’t connect directly to SIP server via TCP or UDP transport. Instead, it connects to Webis server which serves as a proxy between WebRTC app and SIP server. WebRTC app uses WebSocket technology and a proprietary protocol to handle calls and other SIP signalization and Webis communicates with SIP server via standard TCP/UDP socket.

DTLS

WebRTC does not support plain RTP for call media transfer. Instead, it requires DTLS (datagram TLS) encryption. Acrobits mobile apps support DTLS, but most common SIP endpoints and SIP backends don’t. For these situations, Webis serves as an RTP proxy which decrypts/encrypts RTP streams on the fly. The traffic between WebRTC client and Webis will be encrypted using DTLS, traffic between Webis and the remote call party will use plain RTP protocol.

ICE

WebRTC mobile apps heavily use ICE for NAT traversal. Acrobits mobile apps support ICE, but for interoperability with other SIP clients or for off-net calls to PSTN, Webis emulates ICE support and presents ICE-enabled SDPs to WebRTC app, but plain SDP to remote parties.

Codecs

WebRTC apps support a limited set of codecs. Webis currently doesn’t support media transcoding, so you will either have to do it yourself on SIP backend side, or make sure the endpoints in your network support at least one of the following codecs:

Audio:
  • G711 (both a-law and u-law)
  • G722
  • Opus
Video:
  • VP8

Address Book

Unlike mobile apps, WebRTC app doesn’t have access to any local address book. Acrobits Contacts server can be used to show contacts from a mobile app, if the user has it installed. More details about it can be found in Contact Sync document.

Without Contact Sync, or in case the user doesn’t use any mobile app, WebRTC app will start with empty contacts and the user can manually add them.

Enabling basic WebRTC

WebRTC can be enabled by checking “WebRTC” checkbox at Cloud Softphone web portal, when specifying features for the app (Step 1). For non-whitelabel Cloud Softphone apps, the WebRTC client will become available at https://cloud_id.cloudsoftphone.com, white-label apps will be provided as a package which can be hosted at any URL you want.

When WebRTC feature is enabled, a new configuration option appears in “Provisioning options” (Step 2): Webis. Webis component is required for WebRTC to work and you have to specify a valid address to webis server instance. For testing, feel free to use Webis server used by Acrobits, whose address will be pre-filled. For best performance, it’s recommended to use Webis server hosted on your premises for production.

Naturally, you will also have to configure the usual configuration parameters like SIP domain, transport etc.

In theme editor, you will find WebRTC as another supported platform for which you can specify graphics and color scheme.

When done, you can direct your Chrome browser to https://<your_cloud_id>.cloudsoftphone.com and start testing!

WebRTC with Contact Sync

Contact Sync allows sharing of mobile address books between mobile apps and WebRTC app. With this feature enabled, users will see their mobile addressbook (including avatar images) in their WebRTC app.

Enabling Contact Sync requires additional server components and some scripting on provider’s end. We’ll look into them in detail below.

If you have the basic WebRTC app configured and working, the first step to enable Contact Sync is to check “Contact Sync” option in Features (Step 1) of your app. This will reveal several new configuration options in Provisioning Options (Step 2).

External Authentication

External Authentication is a web service which serves as an authority which decides whether username/password combination is valid. The script has to be implemented on providers side, typically by checking user database and verifying that the username/password combination is valid.

The URL of the script is filled in External Authentication section of Provisioning Options. Note that the script will not be called by the mobile or webrtc apps directly, but only from SSO server (see below). You may therefore restrict access to this script and allow only requests from SSO server address.

SSO Server

SSO stands for “single sign-on” server. The function of this server is to manage access rights of the apps to read and write contacts to Contacts server. Clients use access tokens generated by SSO server and Contacts server checks validity of these tokens on SSO server before allowing any operation.

The server can be either hosted by Acrobits, or deployed on premises of provider. Acrobits representative can help you with setup and configuration of this software.

URL of SSO server is configured in “Contact Sync” section of Provisioning Options.

Contacts Server

Contacts server manages server-side storage of contacts, syncing any changes made on mobile devices and providing contacts to WebRTC apps.

Both SSO and Contacts servers are written in Java using Spring framework and require Mongo object database.

The server can be either hosted by Acrobits, or deployed on premises of provider. Acrobits representative can help you with setup and configuration of this software.

URL of Contacts server is configured in “Contact Sync” section of Provisioning Options.

WebRTC with Smart Contacts

Smart Contacts technology allows identifying people in address book which use the same phone service and allowing an alternative way of calling them via doing on-net call (a SIP call to their registered SIP username), instead of an off-net call (calling their phone number via PSTN). See also a separate article about Smart Contacts for more details.

Smart Contacts rely on phone numbers to identify people using the same service. An SMS with verification code must be sent to user during app provisioning to make sure the phone number is correct and really belongs to this user. Only when the user enters correct code, SIP account is provisioned to the app and provider must remember the association between the SIP account and phone number. This association is then provided to Acrobits apps via External Authentication script.

To enable WebRTC with Smart Contacts, you must first enable this feature in Features (Step 1). The section is named “Smart Contacts and Registration Wizard”.

Note

Apps with Smart Contacts need a registration wizard where the user enters phone number and verification code received by SMS. This functionality is only available for full White-Label apps. You will have to use the White Label package to enable Smart Contacts.

You also need to have enabled and configured the “WebRTC with Contact Sync” described in the section above, Smart Contacts extend this functionality.

Enabling the feature will reveal a new configuration option in Whitelabel options (Step 3 of white-label app configuration). The script will receive the phone number entered by user and must send SMS message with verification code to this number. More details are specified in Phone Number Verifier chapter.