Informizely customer feedback surveys
By using the Aculab site, you agree with our use of cookies.

WebRTC Interface Version 2

The interface consists of several JavaScript classes. These classes hide the complexity of the browser's WebRTC APIs and the differences in implementation between the supported browsers. The classes also handle 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.

You can include the JavaScript library by adding the following line to your HTML header:

<script src="https://webrtc.aculabcloud.net/js/2/AculabCloudCaller.js" type="text/javascript"></script>

The version 2 library also includes an implementation of the version 1 interface.

The Application Developer Guide describes how to write applications that use the WebRTC Interface.

API Classes

AculabCloudClient

AculabCloudClient Constructor:

AculabCloudClient.constructor(cloudId, webRtcAccessKey, clientId, logLevel)

Creates an AculabCloudClient object

Parameter Description
cloudId The identifier of the Aculab Cloud where services that interact with the user are located (e.g. 1-2-0).
webRtcAccessKey The WebRTC access key of your Aculab Cloud account.
clientId identifies this client object. It is the value that will be placed in the call_from field in the call details of the application's main channel when making calls to inbound services. It is also the value used when services make outbound calls to WebRTC clients. Must be a valid SIP URI 'user' element, see RFC 3261 - Section 25 for details.
logLevel A numeric value between 0 and 6 inclusive. 0 disables logging and 6 is the most detailed logging.

This throws a string exception if any parameter is invalid.

AculabCloudClient Functions:

static boolean AculabCloudClient.isSupported()

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

AculabCloudOutgoingCall AculabCloudClient.makeOutgoing(serviceName)

This initiates a call to the specified Aculab Cloud incoming service. Call progress is reported by callbacks, these should be set on the object returned by this function.

Parameter Description
serviceName The name of the Aculab Cloud incoming service that the call will be connected to.

This throws a string exception if:

  • the browser doesn't support calling the cloud
  • there are too many calls already in progress
  • serviceName contains disallowed characters

void AculabCloudClient.enableIncoming(token)

This function initiates registration of this client object as the destination for calls to the specified user. The status of the registration is reported by the onIncomingState callback.

Parameter Description
token The token is an authenication token. These are generated using an Aculab Cloud web service. The token can be updated by calling this function with the new token.

This throws a string exception if the token format is invalid.

void AculabCloudClient.disableIncoming()

This function initiates the removal of this client as the destination for call to the specified user. The status of the registration is reported by the onIncomingState callback.

AculabCloudClient Properties:

AculabCloudClient.iceServers

Must be null or an array of RTCIceServer objects. This value can be changed at any time. Outgoing calls will use the value set when the call is made. Incoming calls will use the value set when the call is answered. If the value is null, an Aculab provided set of iceServers is used. Using an empty array will disable the Aculab provided iceServers.

AculabCloudClient.maxConcurrent

This is the number of concurrent calls this client is allowed to handle. The default is 1. This value must be 1 or greater. The upper limit is browser dependent.

AculabCloudClient 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.

AculabCloudClient.onIncomingState

Called when user registration state changes.

Parameter Description
ready A boolean indicating whether this client is waiting for incoming calls.
cause The reason for the registration state change.
retry A boolean indicating whether the client will automatically retry the registration.

The parameter cause will be one of the following strings:

Cause Description
'DISCONNECTED' The connection to the cloud has been lost.
'INVALIDTOKEN' The token specified is not valid (for example, it has expired).
'FAILED' The registration was unsuccessful for some other reason.
'NORMAL' The state change was in response to API calls.

AculabCloudClient.onIncoming

Called when an incoming call occurs. If this is null or throws an exception, the incoming call is rejected.

Parameter Description
call An AculabCloudIncomingCall object.
from The CallerID passed by the calling service.

Call progress is reported by callbacks, these should be set on the passed call object before returning from the callback function.

AculabCloudCall

The base class for call objects. Instances derived from this object are returned by makeOutgoing() or passed in calls to the onIncoming callback.

AculabCloudCall Functions:

void AculabCloudCall.mute(mic, output)

Mutes audio for the call.

Parameter Description
mic A boolean. If true, then the microphone (sent audio) is muted. If false, then the microphone is unmuted.
output A boolean. If true, then the received audio is muted. If false, then the received audio is unmuted.

void AculabCloudCall.sendDtmf(dtmfStr)

Sends DTMF characters.

Parameter Description
dtmfStr 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.

void AculabCloudCall.disconnect()

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

AculabCloudCall Callback Properties:

AculabCloudCall.onDisconnect

The call has disconnected.

Parameter Description
call The call object that is reporting the event.
cause The reason the call disconnected.

The parameter cause will be one of the following strings:

Cause Description
'MIC_ERROR' No microphone is available, usually because the user refused access or there is no microphone.
'BUSY' The 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 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.

AculabCloudCall.onMedia

Called when remote media is available to be played to the user.

Parameter Description
call The call object that is reporting the event.
stream A MediaStream object suitable connecting to an <audio> HTMLMediaElement as the srcObject.

AculabCloudCall.onConnecting

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.

Parameter Description
call The call object that is reporting the event.

AculabCloudCall.onConnected

Called when the call has been answered.

Parameter Description
call The call object that is reporting the event.

AculabCloudOutgoingCall

The class extends AculabCloudCall. This class represents outgoing calls and is returned by AculabCloudClient.makeOutgoing().

AculabCloudOutgoingCall Callback Properties:

AculabCloudOutgoingCall.onRinging

Called when incoming service has signalled that the call is ringing.

Parameter Description
call The call object that is reporting the event.

AculabCloudIncomingCall

The class extends AculabCloudCall. This class represents incoming calls and is passed in calls to the AculabCloudClient.onIncoming() callback.

AculabCloudIncomingCall Functions:

void AculabCloudIncomingCall.ringing()

Notify the calling service that the user is being alerted to the incoming call.

void AculabCloudIncomingCall.answer()

Answer the incoming call.

void AculabCloudIncomingCall.reject(cause)

Reject the incoming call.

Parameter Description
cause The cause to give for rejecting the call. The value should be a SIP response code between 400 and 699 inclusive. If no cause is given or the specified cause is not a number, the cause 486 (Busy Here) will be used.

This throws a string exception if the cause is not in the valid range.