Once the Voice API processes the request, a unique job identifier and a unique message_id for each destination are generated. These are returned in the response similar to the below:
{
"api_job_id": "4359d2d7-2f10-49f3-9ad3-dfc574e14054",
"client_job_id": "123455",
"results": {
"35688000000": {
"message_id": "14570116000720000149"
}
},
"result_info": {
"status_code": "0",
"description": "Job has been queued, Please check the progress via the HTTP Postbacks"
}
}
All responses will come with the appropriate HTTP status code. Furthermore, an additional status_code parameter is returned in the response. On a success request, this parameter would be 0.
Key | Type | Optional | Description |
---|---|---|---|
client_job_id | String | Y |
This field maps to the job identifier if it was specified in the original request. |
api_job_id | String | N |
A unique identifier generated per request. This can be used to track a specific request. |
results | RESULTS[] | Y |
If the job was successfully accepted, this section returns a unique MSGID and custom_id (if provided in request) for each destination. |
result_info | RESULT_INFO | N |
Holds details about the resolution of the request. |
Key | Type | Optional | Description |
---|---|---|---|
message_id | String | N | The unique ID for the Voice message sent. |
custom_id | String | Y | Custom identifier that could have been specified in the request. |
Key | Type | Optional | Description |
---|---|---|---|
status_code | Integer | N |
Holds an integer value of the response status. i.e. : 0 = success, -50 = not authorized (Described in Section 7.8 Error/Success Messages) |
description | String | N |
Holds a text description of the response status. |
Validations are in place in order to make sure that required fields are found before calls are initiated. Whenever a mandatory field is missing (from the request and also from the token), a validation error similar to below is returned:
{
"client_job_id": "123455",
"api_job_id": "7477ad77-2d4f-45bd-884f-7fe226fd6f72",
"result_info": {
"status_code": -89,
"description": "Required 'tts_text' or 'audio_file_url' in the 'voice_content' object"
}
}
All responses will show the appropriate status_code for each request sent. These are described in section. Furthermore, in the description field, the missing field is displayed.
The response received from the REST API will include an HTTP status, response code and a self-explanatory message. The following is a list of all possible messages returned in the response:
Response Message | Response Code | HTTP Status | Description |
---|---|---|---|
Service Unavailable | – | 503 | There is a generic problem within the system’s architecture. |
Server Error | – | 500 | There is a generic problem with the system. |
Invalid JSON Body | -80 | 403 | The request sent has some invalid syntax that is breaking the JSON encoding. |
Cannot use both Audio File and TTS at the same time | -81 | 403 | – |
{param_name} is not allowed | -82 | 403 | The parameter passed is not a valid parameter. Please read the Parameter section. |
Invalid type for ‘destinations’ | -83 | 403 | The destinations element in the request is not an array. |
Missing object called ‘number’ in ‘destinations | -84 | 403 | The “Destinations” element does not have any object with a field called “number”. |
The destination number should have at least have 7 and a maximum of 15 digits | -85 | 403 | The destination phone number does meet the length specification. |
There can only be X destination numbers | -86 | 403 | According to the routing preference, each job has the maximum number of destinations that can be sent per job. This message is shown when this limit is exceeded. |
There are no valid destination numbers in the ‘destinations’ parameter | -87 | 403 | After the phone numbers were sanitized, there were no remaining valid numbers to proceed with. |
The ‘destinations’ Object is missing | -88 | 403 | There should be an element called “destinations” in the main JSON body. This must contain objects with phone number destinations. |
Required ‘tts_text’ or ‘audio_file_url’ in the ‘voice_content’ object | -89 | 403 | The “voice_content” must have at least “tts_text” or “audio_file_url” to determine whether the call is of type Text-To-Speech or Audio |
Cannot use ‘tts’ properties in a call of type ‘Audio’ in the ‘voice_content’ object | -90 | 403 | The “voice_content” element must only have parameters that are related to Audio (There is some TTS parameter in the request). |
“Cannot use ‘audio_file_url’ in a call of type ‘TTS’ in the ‘voice_content’ object | -91 | 403 | The “voice_content” element must only have parameters that are related to TTS (There is some Audio parameter in the request). |
The ‘sender_id’ number {number} should at least have 7 digits and a maximum of 15 digits | -92 | 403 | The sender phone number does not meet the required length specification. |
Parameter ‘enable_menu_response’ has to be either ‘true’ or ‘false’ | -93 | 403 | – |
The ‘tts_text’ should at least have 7 characters and a maximum of 15 | -95 | 403 | – |
The TTS voice selected is invalid. (e.g MAN or WOMAN) | -96 | 403 | – |
The TTS language selected is invalid | -97 | 403 | – |
The ‘voice_content’ Object is missing | -98 | 403 | There should be an element called “voice_content” in the main JSON body. This must contain parameters that define a phone call. |
The ‘job_id’ parameter should at least have 7 characters and a maximum of 15 | -99 | 403 | The JOB ID does not meet the length specification of a minimum of 7 and a maximum of 15 |
There was a problem with your job: {generic_error} | -101 | 403 | An error occurred while trying to check for Funds or phone number Coverage. |
Custom ID {custom_id} is not unique | -102 | 403 | The custom_ids passed along with the destinations are not unique. |
{parameter} should be bigger than 10 | -103 | 403 | The parameter should have a value bigger than 10 seconds (no maximum value) |
{parameter} should be integer | -104 | 403 | The parameter should be of type integer. |
Server too busy | -105 | 403 | Our system is currently too busy to handle your request. Please try again later. |
“The Audio File supplied cannot be downloaded to our servers | -106 | 403 | An error has occurred while handling audio management. |
The Audio File format supplied is Invalid (must be MP3 or WAV). Also ensure that the URL has no spaces or invalid characters and also that the File is reachable via the internet. | -107 | 403 | The URL of audio_file has invalid characters such as spaces or non-standard URL characters. The filename must only have “-” and “_” as non-alphanumeric characters |
The Audio File format supplied is corrupted | -108 | 403 | There was a problem reading the MP3 or WAV to gather the Meta Data |
The Audio File supplied cannot be processed. Please contact customer support | -109 | 403 | There was a problem while downloading the Audio File onto servers |
There was some problems with the Audio File | -110 | 403 | There was a problem while processing the Audio File (Downloading or processing the Meta Data) |
The ‘audio_file_url’ must be valid (starting with http or https) | -111 | 403 | The supplied URL for the audio file must start with HTTP or HTTP and have at least 1 character (e.g http://example.com/hello.mp3) |
Cannot establish service settings | -112 | 403 | There is some problem in our VOIP system |
Could not load the call details | -120 | 403 | The message_id provided passed the validation but there were no records found for it |
Could not verify the Call Message ID | -121 | 403 | The message_id provided was not numeric and/or 20 characters long |
Only 1 Destination allowed, when using a TEST Account | -122 | 403 | While using a TEST account, the user can only send the request to only 1 number (his mobile number). To use the full functionality of the system one must be promoted to FULL Account |
Only the personal mobile phone number {{personal_number}) can used when using a TEST Account | -123 | 403 | While using a TEST account, the user can only call his mobile number. To use the full functionality of the system one must be promoted to FULL Account |
Could not load the Job details | -125 | 403 | The API_JOB_ID provided passed the validation of 36 characters but no job was found |
Could not verify the api_job_id | -126 | 403 | The API_JOB_ID specified was not 36 characters long |
{
"api_job_id": "56021e4d-7x91-42e9-be9c-5de682ad2c2b",
"client_job_id": "123455",
"data": [
{
"type": "voice",
"timestamp": 1457423752,
"micro_timestamp": 1457423752000,
"from": "35699000000",
"job_type": "TTS",
"callback_url": "http://example.com/callback",
"tts_text": "Hello, This is a simple test message",
"tts_voice": "MAN",
"tts_lang": "en-GB",
"message_id": "14571237521680000249",
"client_message_id": "111",
"to": "35699000001",
"ring_date": 1457423756,
"answer_date": false,
"hang_date": 1457423766,
"actual_duration": 0,
"billed_duration": 0,
"status": "UNDELIV",
"error_code": 4017,
"error_description": "USER_BUSY"
}
]
}
Key | Type | Optional | Description |
---|---|---|---|
api_job_id | String | N | The Job ID generated by the API. This is the same ID that was returned in the response when the job was original initiated. |
client_job_id | String | Y | The Job ID supplied by the client during the original request in Section 4.1 . If supplied, this field will be returned. |
data | CALLBACK_INFO | N | Contains information for the specific job alongside all its appertaining calls. |
{
"api_job_id": "56021e4d-7391-42e9-be9x-5de682ad2c2b",
"client_job_id": "123455",
"data": [
{
"type": "voice",
"timestamp": 1457423752,
"micro_timestamp": 1457423752000,
"from": "35699000000",
"job_type": "TTS",
"callback_url": "http://example.com/callback",
"tts_text": "Hello, This is a simple test message”,
"tts_voice": "MAN",
"tts_lang": "en-GB",
"message_id": "14574237521680010249",
"client_message_id": "111",
"to": "35699000001",
"ring_date": 1457423756,
"answer_date": false,
"hang_date": 1457423766,
"actual_duration": 0,
"billed_duration": 0,
"status": "UNDELIV",
"error_code": 4017,
"error_description": "USER_BUSY"
}
]
}
Key | Type | Optional | Description |
---|---|---|---|
api_job_id | String | N | The Job ID generated by the API. This is the same ID that was returned in the response when the job was original initiated. |
client_job_id | String | Y | The Job ID supplied by the client during the original request in Section 4.1 . If supplied, this field will be returned. |
data | CALLBACK_INFO | N |
Contains information for the specific call alongside the job’s details. |
HTTP Status Code | Description |
---|---|
200 | All OK |
400 | Bad Request – The request is invalid and was not understood by the API. |
401 | Unauthorized – Header “Authorization” missing, invalid, or revoked; and/or, your host IP is not in the authorized IPs list. |
403 | The request contains invalid or illegal values. |
404 | Not Found – The endpoint on which the request was sent to, does not exist, or does not implement the API requested. |
405 | Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint. |
500 | Internal Server Error |