Previous version of this API can be found here.

Text To Speech Prompt

Base URL

All requests to Nexmo must be to the base URL. Nexmo provides you with an option of a response as a JSON object, or an XML string-you get to choose which response by selecting the appropriate base URL for your request.

JSON end point

https://api.nexmo.com/tts-prompt/json

XML end point

https://api.nexmo.com/tts-prompt/xml

HTTP Methods

All requests are submitted through the HTTP POST or GET method using UTF-8 encoding and URL encoded values.

Expected "Content-Type" for POST is "application/x-www-form-urlencoded", however we also support "application/json", "application/jsonrequest", "application/x-javascript", "text/json", "text/javascript", "text/x-javascript", "text/x-json" when posting parameters as a JSON object.

Security

To ensure privacy we recommend you use HTTPS for all Nexmo API requests.

Authentication

All requests require your API credentials. You can find these in "API Settings" in your Nexmo Dashboard.

Parameter Description
api_key Required. Your API Key. Ex: api_key=n3xm0rocks
api_secret Required. Your API Secret. Ex: api_secret=12ab34cd

Text To Speech Prompt parameters

Capture data entry

Parameters to be used when the goal of the API is simply to capture digits entered directly on the handset by the end user receiving your call.

Parameter Description
to Required. Phone number in international format and one recipient per request. Ex: to=447525856424 when sending to UK
from Optional. A voice enabled inbound number associated with your account.
text Required. Body of the text message (with a maximum length of 1000 characters), UTF-8 and URL encoded value. Check our tips.
lg Optional. The language used to read the message, expected values are below and en-us "US english" is the default.
voice Optional. The voice to be used female (default) or male
repeat Optional. Define how many times you want to repeat the text message (default is 1 , maximum is 10).
machine_detection Optional. How to behave when an answering machine is detected. If set to true we try to beat the machine and play the message after the beep. If no beep we will close the call. If set to hangup, the call hangs up immediately. The status value in the callback url is set to machine when we close the call.
machine_timeout Optional. Time allocated to analyse if the call has been answered by a machine. Accepts values in ms between 400ms, to maximum 10000ms,(default). Wrong values, will be set to default.
callback Optional. A URL to which Nexmo will send a request when the call ends to notify your application.
max_digits Required. Number of digits (with a maximum of 16) to be entered by the end user.
bye_text Required. Body of the text message played after digits are entered (with a maximum length of 500 characters), UTF-8 and URL encoded value.

Confirm data entry

Parameters to be used when the goal of the API is to capture and confirm digits entered by the the end-user receiving your call.

Parameter Description
to Required. Phone number in international format and one recipient per request. Ex: to=447525856424 when sending to UK
text Required. Body of the text message (with a maximum length of 500 characters), UTF-8 and URL encoded value. Check our tips.
lg Optional. The language used to read the message, expected values are below and en-us "US english" is the default.
voice Optional. The voice to be used female (default) or male
callback Optional. A URL to which Nexmo will send a request when the call ends to notify your application.
max_digits Required. Number of digits (with a maximum of 16) to be entered by the end user.
pin_code Required. Digits expected from end-user (pin code length should be equal to max_digits). Ex: 1234
bye_text Required. Body of the text message played after digits are entered successfully (with a maximum length of 500 characters), UTF-8 and URL encoded value. Ex: "Déjà vu" content will be "D%c3%a9j%c3%a0+vu"
failed_text Required. Body of the text message played after 3 failed attempts (with a maximum length of 500 characters), UTF-8 and URL encoded value. Ex: "Déjà vu" content will be "D%c3%a9j%c3%a0+vu"

Response

Same as Text To Speech.

Call status

Similar to Text To Speech, plus an additional parameter 'digits" including the value entered by the end user.