Voice Messaging

Response

Home » API » Voice Messaging » Response

Response

Create a Call

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.

 

Response Explained

Outer Response

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.

RESULTS

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.

RESULT_INFO

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.

 

Error Response Explained

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.

result_info

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

 

Get Job Details

    
{
    "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"
        }
    ]
}

Response Information

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.

 

Get Call Details

    
{
    "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"
        }
    ]
}

Response Information

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 statuses (for all requests)

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
Get Started