WebRTC Interface Version 1

WebRTC allows you to embed a phone into any web page. A WebRTC capable browser can send audio from a microphone over the internet and play audio it receives in real-time. The Aculab Cloud WebRTC interface provides a way to use this functionality to connect users to an Inbound Service.

The interface consists of a single JavaScript class, AculabCloudCaller. This class hides the complexity of the browser's WebRTC APIs and the differences in implementation between the supported browsers. The class also handles the call set-up and tear-down, with the host page being informed of the call progress by means of callbacks.

Integrating WebRTC

The WebRTC specification is currently a moving target and, along with the rest of the industry, we do our best to keep in step with it. Before deployment, please be sure to try out our WebRTC interface in the environment where you expect to use it.

  • Include the JavaScript library by adding the following line to your HTML header:
    <script src="https://webrtc.aculabcloud.net/js/1/AculabCloudCaller.js" type="text/javascript"></script>
  • In your HTML page, create a WebRTC element by adding the following:
    <audio id="player"></audio>
  • Use our cut down template as a base for your JavaScript code.

API - AculabCloudCaller

Object that provides access to the WebRTC interface on Aculab Cloud. A page can have more than one AculabCloudCaller at a time.

AculabCloudCaller Constructors


Creates an AculabCloudCaller object

AculabCloudCaller Functions:

boolean AculabCloudCaller.isSupported()

Returns true if the browser supports the necessary functionality and false if not.

void AculabCloudCaller. makeCall(cloudid, servicename, callerid)

Initiates the call to the specified Aculab Cloud incoming service. Call progress is reported by the callbacks, so these should be set before calling this function.

Parameter Description
cloudid The identifier of the Aculab Cloud that is hosting the incoming service (e.g. 1-2-0).
servicename The name of the Aculab Cloud incoming service that the call will be connected to. Must be a valid SIP URI 'user' element, see RFC 3261 - Section 25 for details.
callerid The value that will be placed in the call_from field in the call details of the application's main channel. Must be a valid SIP URI 'user' element, see RFC 3261 - Section 25 for details.

This throws a string exception if:
  • the browser doesn't support calling the cloud
  • there is another call already in progress
  • the cloudid is not of the correct format (i.e. X-Y-Z)
  • either servicename or callerid contain disallowed characters

void AculabCloudCaller.sendDtmf(dtmf_str)

Sends a DTMF character.

Parameter Description
dtmf_str A string containing the DTMF digits to be sent. Valid characters are 0,1,2,3,4,5,6,7,8,9,*,#,A,B,C and D.

This throws a string exception if there is an invalid digit in the string. There is no return value.

void AculabCloudCaller.disconnect()

Disconnects any existing call. This can be called at any time.

void AculabCloudCaller. attachMediaStreamToElement(element, stream)

Attaches the media stream stream to the <audio> element. It does not force the element into the playing state.

Parameter Description
element The <audio> element
steam The media stream at attach

This is a helper function to deal with the different ways browsers currently handle attaching media streams to <audio> elements. You may use your own code to perform this action. However, if you have used this function then detachMediaStreamFromElement() must be called when the call disconnects to ensure all resources can be released.

void AculabCloudCaller. detachMediaStreamFromElement(element)

Detaches any current media stream from the <audio> element. This should be called when the call disconnects to ensure the resources are released.

AculabCloudCaller Properties


Must be null or an array of RTCIceServer objects. If used, this must be set before calling makeCall().


Must be a numeric value between 0 and 3 inclusive. 0 disables logging.

AculabCloudCaller Callback Properties

It is possible to set callback functions that trigger on WebRTC events, for example, when the call has disconnected, or ringing. Each of these callback properties must be either null or a function. The function will be passed a single object parameter. Additional information may be included as properties of that object. All such properties are detailed below.


The call has disconnected. The parameter 'cause' will be one of the following strings:

Cause Description
'MIC_ERROR' No microphone is available to the AculabCloudCaller, usually because the user refused access or there is no microphone.
'BUSY' The incoming service called hangup() with the busy cause or the service could not be started (due to limited UAS capacity, for example).
'UNOBTAINABLE' The specified incoming service name does not exist.
'MOVED' The incoming service attempted to redirect the call.
'REJECTED' The call was rejected either by the incoming service or an intermediary.
'NOANSWER' The call did not connect.
'FAILED' The call was unsuccessful for some other reason.
'ERROR' An internal error occurred.
'NORMAL' The call has disconnected in the normal way after having connected.


The incoming service has signalled that the call is ringing.


Called when remote media is available to be rendered to the user. The parameter object will have a 'stream' property:

Parameter Description
stream A MediaStream object suitable for passing to the attachMediaStreamToElement() function above.


Called once the local microphone input has been obtained and the connection to the Aculab Cloud has been established. The browser will now start to prepare the sockets needed to transport the call media. Once this has been done, the request to start the incoming service will be sent.


Called when the incoming service has answered the call.


Called when an internal error has occurred. The parameter object will have the following properties:

Parameter Description
error A string describing the error that has occurred.