Each of the Voice API applications allow you to pass a callback URL to the request. When the placed call is completed, the Voice API will send a POST message to the URL you provided. On this page you can find the content of these callback messages for each of our Voice API applications.
Result codes
When you receive a result on a callback url, you will find a part of the message contains the result of the call.
The result is a piece of JSON code, containing a code and a description.
Variable definition
| Variable | Data type | Length | Required | Description |
|---|---|---|---|---|
| code | Numeric | 2 | Yes | The code of the result |
| description | Alphanumeric | 128 | Yes | The description of the result |
| sip-disconnect-code | Alphanumeric | 3 | No | The SIP disconnect code which determines how the call ended. |
| sip-disconnect-reason | Alphanumeric | 64 | No | The (textual) description of the SIP disconnect code. |
Possible results
| Code | Description | Explanation |
|---|---|---|
| 9 | Cancelled | The call was not answered and was cancelled after a timeout hit (60 seconds) |
| 10 | Finished successfully | The call was placed and answered before ending. |
| 11 | Failed | The call could not be made. |
| 12 | Call rejected | The callee actively refused the call, this could also mean the telecom provider owning the number did, so please check the validity of the number. |
JSON
"result": {
"code": 10,
"description": "Finished successfully",
"sip-disconnect-code": "BYE",
"sip-disconnect-reason": ""
}
DTMF
When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:
Variable definition
| Variable | Data type | Length | Description |
|---|---|---|---|
| type | Alphanumeric | 32 | The type of the instruction. Always “dtmf-finished” for an event that returns the dtmf digits received as the result of a get-dtmf instruction. |
| call-id | UUID / GUID | 36 | The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests. |
| instruction-id | Alphanumeric | 64 | The instruction identifier as supplied with the instruction this event belongs to. |
| caller | Alphanumeric | 25 | This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164. |
| callee | Alphanumeric | 25 | This is the phone number of the callee. Phone numbers are always in international format E.164. |
| result | object | -- | This is the result object which contains the status of the call and its description. |
| started-on | DateTime | 24 | The moment when the call has been started. |
| answered-on | DateTime | 24 | The moment when the call has been answered. |
| finished-on | DateTime | 24 | The moment when the call has been finished. |
| digits | Alphanumeric | 64 | This is the DTMF data that was received, excluding the terminator symbol if it was used (usually #). Empty if no (correct) dtmf input was received from the caller. |
| duration-in-seconds | Numeric | -- | The call duration in seconds. This is the time between the answer of the call and when the call was finished (e.g. hung up). |
JSON
{
"type": "dtmf-finished",
"call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
"instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
"callee": "+316xxxxxxxx",
"caller": "+3176xxxxxxx",
"result": {
"code": 10,
"description": "Finished",
"sip-disconnect-code": "BYE",
"sip-disconnect-reason": ""
},
"started-on": "2018-02-09T11:00:31.752Z",
"answered-on": "2018-02-09T11:00:37.972Z",
"finished-on": "2018-02-09T11:00:48.112Z",
"digits": "1234",
"duration-in-seconds": 10
}
FlowBuilder
When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:
Variable definition
| Variable | Data type | Length | Description |
|---|---|---|---|
| type | Alphanumeric | 32 | The type of the instruction. Always “flowbuilder-finished”. |
| call-id | UUID / GUID | 36 | The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests. |
| instruction-id | Alphanumeric | 64 | The instruction identifier as supplied with the instruction this event belongs to. |
| caller | Alphanumeric | 25 | This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164. |
| callee | Alphanumeric | 25 | This is the phone number of the callee. Phone numbers are always in international format E.164. |
| result | object | -- | This is the result object which contains the status of the call and its description. |
| started-on | DateTime | 24 | The moment when the call has been started. |
| answered-on | DateTime | 24 | The moment when the call has been answered. |
| finished-on | DateTime | 24 | The moment when the call has been finished. |
| voicemail | Boolean | -- | Determines whether the call has been answered with a voicemail or not. |
| duration-in-seconds | Numeric | -- | The call duration in seconds. This is the time between the answer of the call and when the call was finished (e.g. hung up). |
JSON
{
"type": "flowbuilder-finished",
"call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
"instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
"caller": "003176xxxxxxx",
"callee": "00316xxxxxxxx",
"result": {
"code": 10,
"description": "Finished",
"sip-disconnect-code": "BYE",
"sip-disconnect-reason": ""
},
"started-on": "2018-02-09T11:00:31.752Z",
"answered-on": "2018-02-09T11:00:37.972Z",
"finished-on": "2018-02-09T11:00:48.112Z",
"voicemail": false,
"duration-in-seconds": 10
}
Notification
When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:
Variable definition
| Variable | Data type | Length | Description |
|---|---|---|---|
| type | Alphanumeric | 32 | The type of the instruction. Always “notification-finished” when a Text-to-speech or a Audio message has been sent. |
| call-id | UUID / GUID | 36 | The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests. |
| instruction-id | Alphanumeric | 64 | The instruction identifier as supplied with the instruction this event belongs to. |
| caller | Alphanumeric | 25 | This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164. |
| callee | Alphanumeric | 25 | This is the phone number of the callee. Phone numbers are always in international format E.164. |
| result | object | -- | This is the result object which contains the status of the call and its description. |
| started-on | DateTime | 24 | The moment when the call has been started. |
| answered-on | DateTime | 24 | The moment when the call has been answered. |
| finished-on | DateTime | 24 | The moment when the call has been finished. |
| voicemail | Boolean | -- | Determines whether the call has been answered with a voicemail or not. |
| duration-in-seconds | Numeric | -- | The call duration in seconds. This is the time between the answer of the call and when the call was finished (e.g. hung up). |
JSON
{
"type": "notification-finished",
"call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
"instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
"caller": "003176xxxxxxx",
"callee": "00316xxxxxxxx",
"result": {
"code": 10,
"description": "Finished",
"sip-disconnect-code": "BYE",
"sip-disconnect-reason": ""
},
"started-on": "2018-02-09T11:00:31.752Z",
"answered-on": "2018-02-09T11:00:37.972Z",
"finished-on": "2018-02-09T11:00:48.112Z",
"voicemail": false,
"duration-in-seconds": 10
}
One Time Password (OTP)
When the call is completed, the CM Server(s) will send a POST command to your server (at the supplied callback url), with a JSON body, with the following content:
Variable definition
| Variable | Data type | Length | Description |
|---|---|---|---|
| type | Alphanumeric | 32 | The type of the instruction. Always “otp-finished” when a OTP message has been sent. |
| call-id | UUID / GUID | 36 | The 36 character (lowercase, including dashes) hexadecimal representation of the call identifier. This number is included in all requests. |
| instruction-id | Alphanumeric | 64 | The instruction identifier as supplied with the instruction this event belongs to. |
| caller | Alphanumeric | 25 | This is the phone number of the caller, if known, “anonymous” otherwise. Phone numbers are always in international format E.164. |
| callee | Alphanumeric | 25 | This is the phone number of the callee. Phone numbers are always in international format E.164. |
| result | object | -- | This is the result object which contains the status of the call and its description. |
| started-on | DateTime | 24 | The moment when the call has been started. |
| answered-on | DateTime | 24 | The moment when the call has been answered. |
| finished-on | DateTime | 24 | The moment when the call has been finished. |
| duration-in-seconds | Numeric | -- | The call duration in seconds. This is the time between the answer of the call and when the call was finished (e.g. hung up). |
JSON
{
"type": "otp-finished",
"call-id": "6d0f176e-00ac-4de2-a04d-b3f7c895adb0",
"instruction-id": "aeba8cae-eadd-4b49-9350-8061893b3d66",
"callee": "+316xxxxxxxx",
"caller": "+3176xxxxxxx",
"result": {
"code": 10,
"description": "Finished",
"sip-disconnect-code": "BYE",
"sip-disconnect-reason": ""
},
"started-on": "2018-02-09T11:00:31.752Z",
"answered-on": "2018-02-09T11:00:37.972Z",
"finished-on": "2018-02-09T11:00:48.112Z",
"duration-in-seconds": 10
}