AculabCloudClient javascript interface
Constructor
AculabCloudClient(cloudId, webRtcAccessKey, clientId, logLevel)
Creates an AculabCloudClient object. A page can have more than one AculabCloudClient at a time.
cloudId is the identifier of the Aculab Cloud where services that interact with the user are located.
webRtcAccessKey is 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.
clientId must be a valid SIP URI 'user' element, see RFC 3261 - Section 25 for details.
logLevel is a numeric value between 0 and 6 inclusive. 0 disables logging and 6 is the most detailed logging.
AculabCloudClient object functions
static boolean isSupported()
Returns true if the browser supports the necessary functionality and false if not.
AculabCloudOutgoingCall makeOutgoing(serviceName)
serviceName is the name of the Aculab Cloud incoming service that the call will be connected to.
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.
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 enableIncoming(token)
token is an authenication token. These can be obtained using an Aculab Cloud webservice. The token can be updated by calling this function with the new 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.
This throws a string exception if the token format is invalid.
void 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 data properties
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
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
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.
onIncomingState
Called when user registration state changes.
The parameter object will have the following properties:
| property | value |
|---|
ready | A boolean indicating whether this client is waiting for incoming calls. |
cause | One of the following strings:
- '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
|
retry | A boolean indicating whether the client will automatically retry the registration. |
onIncoming
Called when an incoming call occurs. If this is null or throws an exception, the incoming call is rejected.
The parameter object will have the following properties:
| property | value |
|---|
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 to the onIncoming callback.
AculabCloudCall object functions
void mute(mic, output)
mic and output are boolean. If mic is true, then the microphone (sent audio) is muted. If output is true the received audio is muted.
void sendDtmf(dtmf_str)
dtmf_str is a string containing the DTMF digits to be sent. These 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 disconnect()
Disconnects any existing call. This can be called at any time.
AculabCloudClient callback properties
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.
onDisconnect
The call has disconnected.
The parameter object will have the following properties:
| property | value |
|---|
call | The call object that is reporting the event. |
cause | One of the following strings:
- 'MIC_ERROR'
- no microphone is available to the AculabCloudClient, 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
Called when remote media is available to be rendered to the user.
The parameter object will have the following properties:
| property | value |
|---|
call | The call object that is reporting the event. |
stream | A MediaStream object suitable connecting to an <audio> HTMLMediaElement as the srcObject.
|
onConnecting
Called once the local microphone input has been obtained and the browser will now start to prepare the sockets needed to transport the call media.
The parameter object will have the following properties:
| property | value |
|---|
call | The call object that is reporting the event. |
onConnected
Called when the call has been answered.
The parameter object will have the following properties:
| property | value |
|---|
call | The call object that is reporting the event. |
AculabCloudOutgoingCall extends AculabCloudCall
The class for outgoing call objects as returned by makeOutgoing(). No additional functions are defined.
AculabCloudOutgoingCall callback properties
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.
onRinging
The incoming service has signalled that the call is ringing.
The parameter object will have the following properties:
| property | value |
|---|
call | The call object that is reporting the event. |
AculabCloudIncomingCall extends AculabCloudCall
The class for incoming call objects passed to the onIncoming callback. No additional callbacks are defined.
AculabCloudIncomingCall object functions
void answer()
Answer the incoming call.
void ringing()
Notify the calling service that the user is being alerted to the incoming call.
void reject(cause)
Reject the incoming call with the cause value specified. The value should be a SIP response code between 400 and 699 inclusive. If no cause is given or the specified cause is invalid, the cause 486 (Busy Here) will be used.