Introduction

Enhance how you communicate using Fortytwo Voice. With our Voice messaging solution, you can broadcast your message through a voice call directly to your customer’s mobile or landline phone worldwide.

Using Fortytwo Voice, it has never been easier to engage your audience. Enhance your customer experience with our Voice API.

There are two simple options to for you to choose from:

Text-To-Speech (TTS)

  • Send a message using the Text-To-Speech (TTS) option which converts your written text into spoken voice in your language of choice (See tts_lang)
  • A Text-to-Speech engine will read out any given text in 15 languages and in different genders

 

Audio File

  • Send a pre-recorded audio file to your customer
  • The file is played directly onto the client’s handset or phone.
  • The maximum file size is set up to 5mb.

 

Other Features

– Allow end clients to input a keypress (0-9) during or after the call, and is mainly used for statistical purposes.

– Daily emails with usage reports

– Track campaigns through our Client Control Panel. We also offer the functionality to download CSV files with detailed information per call.

 

Send Voice Call

Receiving Voice Call

Overview

HTTP Headers

 

Content-Type: application/json; charset=utf-8

 

Authentication

Endpoints

Trigger Call

Trigger a phone call directly on a mobile phone or landline and play an audio message. Messages can be either TTS (Text-to-Speech) or Audio Clips that are hosted reachable via a publicly available URL. (e.g http://example.com/clip.mp3).

After the message is played, there is also an option to accept a response from the user via keypresses (0-9).

The data gathered via these phone calls including delivery statistics is sent to your own personal callback server and also available to export as CSV in our Client Control Panel.

Request

In order to initiate a call, a number of parameters should be passed in the body of the API request sent to the API. Eventually, all destinations provided in the requested are called. The request should be encoded in JSON.

POST
https://rest.fortytwo.com/1/voice/call

Response

Example

Get Call Details

Retrieve the data for a particular phone call. This will return data such as API Job ID, Message ID, Status, Timestamps, Error Codes etc.

Request

GET
https://rest.fortytwo.com/1/voice/call/status/{message_id}

 
When a call is initiated, each destination will have a unique identifier called message_id. This is returned in the response when the Voice API is called. By supplying such message_id in this endpoint, the latest and all relevant information regarding that call is supplied.

Response

Example

GET /1/voice/call/status/{message_id} HTTP/1.1
Host: https://rest.fortytwo.com
Content-Type: application/json; charset=utf-8
Authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://rest.fortytwo.com/1/voice/call/status/{message_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX",
    "content-type: application/json; charset=utf-8"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl -X GET -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX" "https://rest.fortytwo.com/1/voice/call/status/{message_id}"
import requests

url = "https://rest.fortytwo.com/1/voice/call/status/{message_id}"

headers = {
    'content-type': "application/json; charset=utf-8",
    'authorization': "Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)

 

Get Job Details

Retrieve the data for a particular Job (which includes a list of calls that were sent in a single API call). This will return an array of calls and display data such as API Job ID, Message ID, Status, Timestamps, Error Codes etc.

Request

GET
https://rest.fortytwo.com/1/voice/job/status/{api_job_id}

 
When a job (API Call) is initiated, a field called api_job_id is returned in the response. This endpoint is used to retrieve all the relevant information about a job based on this identifier.

Response

Example

GET /1/voice/job/status/{api_job_id} HTTP/1.1
Host: https://rest.fortytwo.com
Content-Type: application/json; charset=utf-8
Authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://rest.fortytwo.com/1/voice/job/status/{api_job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX",
    "content-type: application/json; charset=utf-8"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl -X GET -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX" "https://rest.fortytwo.com/1/voice/job/status/{api_job_id}"
import requests

url = "https://rest.fortytwo.com//1/voice/job/status/{api_job_id}"

headers = {
    'content-type': "application/json; charset=utf-8",
    'authorization': "Token 93a89134-d109-4d60-a8aa-7bc93aXXXXXX"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)

 

Callbacks

Voice supports HTTP POST callbacks, meaning that you can have an endpoint on your own server which will receive callbacks whenever something happens. This is used to track phone calls and allow you to build custom statistics. This callback URL must be publicly available on the internet and have our IP whitelisted (if the system has a firewall).

Delivery Reports and any other relevant intermediary status are signalled back to the client using an HTTP callback. The URL invoked is obtained from the “callback_url” field in the original message request.

An HTTP POST request is sent to the specified callback_url in the following scenarios:

  • When a call is ringing
  • When a call failed
  • When client has no sufficient funds to perform the call
  • When there is no coverage for destination
  • When the call was delivered

 

Whitelist callback server

You may need to configure your firewall to whitelist traffic from these IP addresses:

IPv4: 80.252.167.60

Note that these IPs can change in the future.
 

Response HTTP Status Code

The HTTP Callback on your server should return the correct HTTP Headers containing 200 OK. If the client’s server is unreachable or does not return a 200 OK, the callback is queued to be retried again. After three failed attempts, with an interval of 5 minutes between them, the callback is discarded.

Call Callbacks

Server Example

Examples for Servers that accept HTTP POST Callbacks
$postRawData = file_get_contents("php://input");
$json = json_decode($postRawData, true);
var_dump($json);

 

References

HTTP Status Codes

When responding, the REST API will make use of the appropriate and relevant HTTP status code to describe the nature of the result.

The response codes are mapped as follows:
HTTP Status 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.
413 Request entity was too large.
415 Unsupported Media Type – If the request was in a content-type not supported by the endpoint (e.g. text/plain instead of application/json).
429 Too many requests (Throttling).
500 Internal Server Error.

 

Response Call Object

Call Error Codes

Code Label Description
0 NORMAL_CLEARING The call was successful and was picked up by the destination number. This indicates that the call is being cleared because one of the users involved in the call has requested that the call be cleared.
3000 UNSPECIFIED There was no specific error.
3001 SERVER_TOO_BUSY The system cannot process any more traffic at the moment, thus the job is rejected.
3002 NO_COVERAGE There was no coverage for the particular call destination, thus the call was not initiated. Ensure that the destination number is valid (incl the country prefix). Please contact our Customer Support for a more detailed overview
3003 NO_FUNDS There were not enough funds for the particular call, thus the call was not initiated.
3004 PAYMENT_ERROR There was a problem processing the call charge
3005 FAILED_AUDIO_DOWNLOAD This happens when the audio file cannot be downloaded due to an invalid or unreachable audio file URL.
4000 UNSPECIFIED No other cause codes applicable. This is usually given by the router when none of the other codes apply. This cause usually occurs in the same type of situations as cause 1, cause 88, and cause 100.
4001 UNALLOCATED_NUMBER This cause indicates that the called party cannot be reached because, although the called party number is in a valid format, it is not currently allocated (assigned).
4002 NO_ROUTE_TRANSIT_ NET This cause indicates that the equipment sending this cause has received a request to route the call through a particular transit network, which it does not recognize. The equipment sending this cause does not recognize the transit network either because
the transit network does not exist or because that particular transit network, while it does exist, does not serve the equipment which is sending this cause.
4003 NO_ROUTE_DESTINA TION This cause indicates that the called party cannot be reached because the network through which the call has been routed does not serve the destination desired. This cause is supported on a network dependent basis.
4006 CHANNEL_UNACCEP TABLE This cause indicates that the channel most recently identified is not acceptable to the sending entity for use in this call.
4007 CALL_AWARDED_DEL IVERED This cause indicates that the user has been awarded the incoming call, and that the incoming call is being connected to a channel already established to that user for similar calls (e.g. packet-mode x.25 virtual calls).
4017 USER_BUSY This cause is used to indicate that the called party is unable to accept another call because the user busy condition has been encountered. This cause value may be generated by the called user or by the network. In the case of user determined user busy
it is noted that the user equipment is compatible with the call.
4018 NO_USER_RESPONSE This cause is used when a called party does not respond to a call establishment message with either an alerting or connect indication within the prescribed period of time allocated.
4019 NO_ANSWER This cause is used when the called party has been alerted but does not respond with a connect indication within a prescribed period of time. Note – This cause is not necessarily generated by Q.931 procedures but may be generated by internal network timers.
4020 SUBSCRIBER_ABSENT This cause value is used when a mobile station has logged off, radio contact is not obtained with a mobile station or if a personal telecommunication user is temporarily not addressable at any user-network interface. Sofia SIP will normally raise USER_NOT_REGISTERED
in such situations.
4021 CALL_REJECTED This cause indicates that the equipment sending this cause does not wish to accept this call, although it could have accepted the call because the equipment sending this cause is neither busy nor incompatible. The network may also generate this cause,
indicating that the call was cleared due to a supplementary service constraint. The diagnostic field may contain additional information about the supplementary service and reason for rejection.
4022 NUMBER_CHANGED This cause is returned to a calling party when the called party number indicated by the calling party is no longer assigned, The new called party number may optionally be included in the diagnostic field. If a network does not support this cause, cause
no: 1, unallocated (unassigned) number shall be used.
4023 REDIRECTION_TO_NEW_DESTINATION This cause is used by a general ISUP protocol mechanism that can be invoked by an exchange that decides that the call should be set-up to a different called number. Such an exchange can invoke a redirection mechanism, by use of this cause value, to request
a preceding exchange involved in the call to route the call to the new number.
4025 EXCHANGE_ROUTING_ERROR This cause indicates that the destination indicated by the user cannot be reached, because an intermediate exchange has released the call due to reaching a limit in executing the hop counter procedure. This cause is generated by an intermediate node,
which when decrementing the hop counter value, gives the result 0.
4027 DESTINATION_OUT_OF_ORDER This cause indicates that the destination indicated by the user cannot be reached because the interface to the destination is not functioning correctly. The term “not functioning correctly” indicates that a signal message was unable to be delivered to
the remote party; e.g. a physical layer or data link layer failure at the remote party, or user equipment off-line.
4028 INVALID_NUMBER_FORMAT This cause indicates that the called party cannot be reached because the called party number is not in a valid format or is not complete.
4029 FACILITY_REJECTED This cause is returned when a supplementary service requested by the user cannot be provide by the network.
4030 RESPONSE_TO_STATUS_ENQUIRY This cause is included in the STATUS message when the reason for generating the STATUS message was the prior receipt of a STATUS INQUIRY.
4031 NORMAL_UNSPECIFIED This cause is used to report a normal event only when no other cause in the normal class applies.
4034 NORMAL_CIRCUIT_CONGESTION This cause indicates that there is no appropriate circuit/channel presently available to handle the call.
4038 NETWORK_OUT_OF_ORDER This cause indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time e.g. immediately re-attempting the call is not likely to be successful.
4041 NORMAL_TEMPORARY_FAILURE This cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g. the user may wish to try another call attempt almost immediately.
4042 SWITCH_CONGESTION This cause indicates that the switching equipment generating this cause is experiencing a period of high traffic.
4043 ACCESS_INFO_DISCARDED This cause indicates that the network could not deliver access information to the remote user as requested, i.e. user-to-user information, low layer compatibility, high layer compatibility or sub-address as indicated in the diagnostic. It is noted that
the particular type of access information discarded is optionally included in the diagnostic.
4044 REQUESTED_CHAN_UNAVAIL This cause is returned when the other side of the interface cannot provide the circuit or channel indicated by the requesting entity.
4050 FACILITY_NOT_SUBSCRIBED This cause indicates that the user has requested a supplementary service, which is available, but the user is not authorized to use.
4052 OUTGOING_CALL_BARRED This cause indicates that although the calling party is a member of the CUG for the outgoing CUG call, outgoing calls are not allowed for this member of the CUG.
4054 INCOMING_CALL_BARRED This cause indicates that although the called party is a member of the CUG for the incoming CUG call, incoming calls are not allowed to this member of the CUG.
4057 BEARERCAPABILITY_NOTAUTH This cause indicates that the user has requested a bearer capability that is implemented by the equipment which generated this cause but the user is not authorized to use.
4058 BEARERCAPABILITY_NOTAVAIL This cause indicates that the user has requested a bearer capability which is implemented by the equipment which generated this cause but which is not available at this time.
4063 SERVICE_UNAVAILABLE This cause is used to report a service or option not available event only when no other cause in the service or option not available class applies.
4065 BEARERCAPABILITY_NOTIMPL This cause indicates that the equipment sending this cause does not support the bearer capability requested.
4066 CHAN_NOT_IMPLEMENTED This cause indicates that the equipment sending this cause does not support the channel type requested
4069 FACILITY_NOT_IMPLEMENTED This cause indicates that the equipment sending this cause does not support the requested supplementary services.
4079 SERVICE_NOT_IMPLEMENTED This cause is used to report a service or option not implemented event only when no other cause in the service or option not implemented class applies.
4081 INVALID_CALL_REFERENCE This cause indicates that the equipment sending this cause has received a message with a call reference which is not currently in use on the user-network interface.
4088 INCOMPATIBLE_DESTINATION This cause indicates that the equipment sending this cause has received a request to establish a call which has low layer compatibility, high layer compatibility or other compatibility attributes (e.g. data rate) which cannot be accommodated.
4095 INVALID_MSG_UNSPECIFIED This cause is used to report an invalid message event only when no other cause in the invalid message class applies.
4096 MANDATORY_IE_MISSING This cause indicates that the equipment sending this cause has received a message which is missing an information element which must be present in the message before that message can be processed.
4097 MESSAGE_TYPE_NONEXIST This cause indicates that the equipment sending this cause has received a message with a message type it does not recognize either because this is a message not defined of defined but not implemented by the equipment sending this cause.
4098 WRONG_MESSAGE This cause indicates that the equipment sending this cause has received a message such that the procedures do not indicate that this is a permissible message to receive while in the call state, or a STATUS message was received indicating an incompatible
call state.
4099 IE_NONEXIST This cause indicates that the equipment sending this cause has received a message which includes information element(s)/parameter(s) not recognized because the information element(s)/parameter name(s) are not defined or are defined but not implemented
by the equipment sending the cause. This cause indicates that the information element(s)/parameter(s) were discarded. However, the information element is not required to be present in the message in order for the equipment sending the
cause to process the message.
4100 INVALID_IE_CONTENTS This cause indicates that the equipment sending this cause has received and information element which it has implemented; however, one or more fields in the I.E. are coded in such a way which has not been implemented by the equipment sending this cause.
4101 WRONG_CALL_STATE This cause indicates that a message has been received which is incompatible with the call state.
4102 RECOVERY_ON_TIMER_EXPIRE This cause indicates that a procedure has been initiated by the expiration of a timer in association with error handling procedures. This is often associated with NAT problems. Ensure that “NAT Mapping Enable” is turned on in your ATA. If it is not NAT
related it can sometimes be provider related, make sure to ensure another outbound provider does not solve the problem.
4103 MANDATORY_IE_LENGTH_ERROR This cause indicates that the equipment sending this cause has received a message which includes parameters not recognized because the parameters are not defined or are defined but not implemented by the equipment sending this cause. The cause indicates
that the parameter(s) were ignored. In addition, if the equipment sending this cause is an intermediate point, then this cause indicates that the parameter(s) were passed unchanged.
4111 PROTOCOL_ERROR This cause is used to report a protocol error event only when no other cause in the protocol error class applies.
4127 INTERWORKING This cause indicates that an interworking call (usually a call to SW56 service) has ended.
4128 ORIGINATOR_CANCEL The system interrupted the call likely due to timeouts set by the request.
4602 ALLOTTED_TIMEOUT This cause means that the server canceled the call because the destination channel took too long to answer.