Talk To Us!
WebSockets
Overview
The WebSocket Protocol enables two-way communication between a client and a server. When Aculab Cloud communicates over a WebSocket, it takes the client role and connects to your server.
Aculab Cloud offers v2.ws.cloud.aculab.com and v1.ws.cloud.aculab.com in the Sec-WebSocket-Protocol header. These protocols use text frames to send JSON strings representing information and control message objects. Each object has a "type" property, to identify the format of the message. Binary frames are used to pass raw audio data.
The v2.ws.cloud.aculab.com protocol notifies the server of DTMF using DTMF event messages, and replaces audio containing DTMF with silence in the data sent to the server. Whereas, the v1.ws.cloud.aculab.com protocol passes DTMF in the audio sent to the server and will not send any DTMF event messages.
The server should include the protocol it expects to use in the response's Sec-WebSocket-Protocol header. If no protocol or v1.ws.cloud.aculab.com is returned, then the v1.ws.cloud.aculab.com will be used. Only if v2.ws.cloud.aculab.com is returned will v2.ws.aculab.com be selected.
Calls to WebSockets
Applications running in Aculab Cloud can make outbound calls to WebSockets. For example, a REST application can use the Connect action with the destination set to a secure WebSocket URL.
The initial WebSocket connection uses an HTTP request. If that request returns a status other than "101 Switching Protocols", then the HTTP response status code will be passed to the application as the call raw cause. For example, if the server returns "404 Not Found" then the call raw cause will be 404.
If there is a problem connecting to the URL specified, one of the following call raw cause values may be passed to the application:
| Call raw cause | Description |
|---|---|
| 900 | An error that was not classified. |
| 901 | The URL could not be parsed. |
| 902 | The DNS name from the URL could not be resolved. |
| 903 | A connection could not be made to the server. |
| 904 | The transport layer security (TLS) handshake failed. This is usually a certifcate problem. |
| 905 | The WebSocket handshake failed without returning a valid HTTP response status code. |
Once the WebSocket is connected, the server can end the call by sending a call hangup message. In this case the "raw_cause" specified in that message will be passed to the application. If the WebSocket is closed with a WebSocket Close frame, then the status code in that frame will be passed to the application.
When the application ends the WebSocket call, the call raw cause passed to the application will be 0.
Messages from Aculab Cloud
- Call start
- Audio start
- Audio end
- Call end
- Audio play finished
- Error
- Audio overflow warning
- DTMF event
Call start
The first message sent when an outbound call is made to a websocket.
| Property | Description |
|---|---|
| type | "call_start" |
| from | The caller's number or SIP address. |
Audio start
Provides details of the audio data that will follow. Each binary frame from Aculab Cloud will normally contain 20ms of audio data.
| Property | Description |
|---|---|
| type | "audio_start" |
| format | The encoding used for the audio data. One of:
|
| sample_rate | The sample rate of the audio data. Currently always 8000. |
| channels | The number of channels in the audio data. This is either 1 or 2. For calls to WebSockets, this is 1. |
Audio end
Indicates that the last of the audio data has been sent.
| Property | Description |
|---|---|
| type | "audio_end" |
Call end
This message is sent when a call ends. The WebSocket connection is closed after this message.
| Property | Description |
|---|---|
| type | "call_end" |
| origin | One of:
|
| cause | The call completion cause. One of:
|
| raw_cause | The cause code used to end the call. This is normally 0 for calls ended by the application. |
Audio play finished
Indicates that a play initiated by a audio play start has finished. This is always sent when a play finishes, whether it ended normally, was aborted or the call ends.
| Property | Description |
|---|---|
| type | "audio_play_finished" |
| id | The id from the corresponding audio play start. |
Error
Reports that a message was received that was not understood or could not be processed at that point.
| Property | Description |
|---|---|
| type | "error" |
| reason | A description of the problem with the received frame. |
Audio overflow warning
Indicates that Aculab Cloud is dropping audio data because the send queue is full. This means that the WebSocket has been unable to send frames, usually because the server is not reading them fast enough.
| Property | Description |
|---|---|
| type | "audio_overflow_warning" |
DTMF event
Indicates the detection of DTMF in the audio.Only sent if the protocol is "v2.ws.cloud.aculab.com".
| Property | Description |
|---|---|
| type | "dtmf_event" |
| digit | The DTMF digit detected. |
| duration_ms | The duration of the detected tone, in milliseconds. |
| end_of_digit | true or false. Indicates if the digit has ended or not. |
| direction | "in" or "out". Indicates the direction of the audio containing the digit. (not present for calls to websockets) |
Messages to Aculab Cloud
When a call is made to a WebSocket, the server may send messages to Aculab Cloud to play audio through the WebSocket or to disconnect the call.
All frames sent, whether text or binary, may have a payload of up to 1600 bytes. Frames that exceed this limit will cause the connection to be closed.
Audio play start
Starts a new audio play and provides details of the audio data that will follow. Each binary frame must contain a whole number of samples. It is strongly recommended that a multiple of 10ms of data is included in each frame. Aculab Cloud will queue up to 250 audio data frames for each audio play when the frames are sent faster than real-time. The audio data frames should to be paced to not exceed the queue size.
| Property | Default | Description |
|---|---|---|
| type | "audio_play_start" | |
| format | "16bit_PCM" | The encoding used for the audio data. One of:
|
| sample_rate | 8000 | The sample rate of the audio data. Currently, only 8000 is supported. |
| channels | 1 | The number of channels in the audio data. This is either 1 or 2. |
| channel | 0 | Which channel of the audio to play. This is either 0, 1 or 2. For mono audio data, either 0 or 1 can be used. For 2 channel audio, 0 will mix the two channels together (only supported with "16bit_PCM" data). |
| initial_buffer_ms | 100 | The amount of audio data to buffer before starting to play. When sending the audio in real-time, this can reduce the risk of delays causing audio gaps. |
| id | "" | An identifier. This will be included in an audio play end message when the play ends. |
Audio play end
Indicates that the last of the audio play data has been sent. A new audio play can be started after this message without waiting for the audio play finished to arrive.
Aculab Cloud allows up to 4 audio plays to be queued at a time.
| Property | Default | Description |
|---|---|---|
| type | "audio_play_end" |
Audio play abort
Aborts all active and queued audio plays. All audio data sent before this message, and not yet played, is discarded. A new audio play can be started after this message without waiting for audio play finished messages to arrive.
| Property | Default | Description |
|---|---|---|
| type | "audio_play_abort" |
Call hangup
Tell Aculab Cloud to hangup the call.
| Property | Default | Description |
|---|---|---|
| type | "call_hangup" | |
| cause | "NORMAL" | The call completion cause to pass to the application. One of:
|
| raw_cause | 0 | The raw cause code to pass to the application. |