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.

The callback properties of each object instance must be either null or a function. When an event occurs, the function will be passed a single object parameter. Information about the event is included as properties of that object. All such properties are detailed below.

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.

• AculabCloudClient
• AculabCloudCall
• AculabCloudOutgoingCall
• AculabCloudIncomingCall

• 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. This can only contain alphanumeric and +-._ characters.
  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.

• isSupported

  static boolean AculabCloudClient.isSupported()

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

• makeOutgoing

  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

• enableIncoming

  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.

• disableIncoming

  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.

• iceServers

  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.

• maxConcurrent

  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.

• onIncomingState

  AculabCloudClient.onIncomingState

  Called when user registration state changes.

  The object passed to the callback has the following properties:

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

  The property 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

• onIncoming

  AculabCloudClient.onIncoming

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

  The object passed to the callback has the following properties:

  Property	Description
  call	An AculabCloudIncomingCall object.
  from	The CallerID passed by the remote party.

  The progress of the incoming call is reported by callbacks. These should be set on the passed call object before returning from the callback function.

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

• mute

  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.

• sendDtmf

  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.

• disconnect

  void AculabCloudCall.disconnect()

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

• onDisconnect

  AculabCloudCall.onDisconnect

  The call has disconnected.

  The object passed to the callback has the following properties:

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

  The property 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.

• onMedia

  AculabCloudCall.onMedia

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

  The object passed to the callback has the following properties:

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

• onConnecting

  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.

  The object passed to the callback has the following properties:

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

• onConnected

  AculabCloudCall.onConnected

  Called when the call has been answered.

  The object passed to the callback has the following properties:

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

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

• onRinging

  AculabCloudOutgoingCall.onRinging

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

  The object passed to the callback has the following properties:

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

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

• ringing

  void AculabCloudIncomingCall.ringing()

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

• answer

  void AculabCloudIncomingCall.answer(options)

  Answer the incoming call.

• reject

  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.