post

/voice

Send a voice message (with a verification code if you wish), specify the type of message, what phase of the account lifecycle the message is being sent in, what language to speak the message in, and additional details about the transaction. NOTE: If you try this API out using the API Explorer, you will be billed for the transaction as you normally would.

All requests submitted for the Voice API:

  • Can be authenticated with Basic (easiest to implement) and Digest.
  • Use https://rest-api.telesign.com/v1/voice as the base endpoint.
  • Accept only UTF-8 encoded unicode characters as inputs.
  • Use Content-Type application/x-www-form-urlencoded in request headers.

Authorization

basic

Request Body

Schema
object
phone_number
string

The end user’s phone number with country code included. Avoid use of special characters and spaces.

required
message
string

Text of the message to be converted to speech and sent to the end user. You are limited to 1600 characters.

required
message_type
string

This parameter specifies the traffic type being sent in the message. You can provide one of the following values -

  • OTP (One time passwords)
  • ARN (Alerts, reminders, and notifications)
  • MKT (Marketing traffic)
required
voice
string

The voice parameter allows you to specify a voice to be used to speak your text to speech message. If you do not specify a voice, the default f-en-US is used. At this time, all TeleSign voices are female. Available options for this parameter include-

Language Language Tag
Chinese (Hong Kong, Cantonese) f-zh-HK
Chinese (Mandarin) f-zh-CN
Chinese (Taiwan) f-zh-TW
Danish f-da-DK
Dutch f-nl-NL
English (Australian) f-en-AU
English (UK) f-en-GB
English (US) f-en-US
English (Canadian) f-en-CA
English (India) f-en-IN
Finnish f-fi-FI
French f-fr-FR
French (Canadian) f-fr-CA
Italian f-it-IT
Japanese f-ja-JP
Korean f-ko-KR
Norweigan f-nb-NO
Polish f-pl-PL
Portuguese (Brazil) f-pt-BR
Portuguese (Europe) f-pt-PT
Spanish (Mexico) f-es-MX
Spanish (Spain, Castilian) f-es-ES
select_digits
string

A string of digits that can be up to 10 digits long with no repeats (0-9). Any digits in the string you provide are individually valid to accept. For example, ‘12’ would mean you want the end user to be able to press 1 or 2. You would use this in conjunction with the message parameter, and in your message be sure to specify what each choice is for the end user. NOTE: Do NOT include the digit you want to use to play ‘repeat this message’ with. Use the repeat_digit parameter for that.

repeat_digit
string

A single digit provided as a string that you want the end user to be able to press in order to hear the message you put in the ‘message’ parameter again. The end user can press this digit three times and hear a message that you choose in the ‘tts_repeat’ parameter, followed by the original message you put in the ‘message’ parameter. (For example, if ‘message’ is Press 1 to confirm, 2 cancel, 3 to hear this again… if the end user presses 3, they get the message you put in for the ‘tts_repeat’ parameter followed by the message in the ‘message’ parameter.) The end user can repeat the message up to 3 times. If they try to repeat a fourth time, the system hangs up on them.

tts_message_n
string

A text to speech message to be played when the end user presses the appropriate digit. In the parameter name, the ‘n’ stands in for the digit. If you decided the end user could press 1 or 2, then you would ideally have a tts_message_1 and a tts_message_2, each with an associated message to play. The system hangs up after the message plays. It hangs up immediately if the end user presses a digit during play.

tts_repeat
string

This is the message that plays when the end user presses the digit you specified for the repeat_digit parameter. The end user can hear this message up to three times. If they try to hear it a fourth time, the system hangs up on them.

prompt_message
string

This message is to be used in conjunction with prompt_digit. You provide a message to play, it is converted to text-to-speech and sent in a call and played for the end user. The message should contain the digit you want to press. For example, you might have the message Press 7 to continue. Make sure the digit in your message matches the digit you send for prompt_digit. If the end user presses the correct digit, then the message you have for the message parameter plays. If the end user does not press the correct digit, the follow up message does not play. All messages use the same voice tag if you choose to include one.

prompt_digit
string

This digit is to be used in conjunction with prompt_message. Provide a single digit 0-9 that you want the end user to press. After playing the prompt message, the system will wait and give the end user two chances to press the correct digit. If they do, the message in the message parameter plays. All messages use the same voice tag if you choose to include one.

caller_id
string

This parameter allows you to set a phone number as caller ID for a VOice API message sent to your end users. In order to use a specific caller ID, you must purchase a phone number from TeleSign. This can be done with your account at portal.telesign.com. Be aware that 100% preservation of a caller ID value is not guaranteed. TheeSign or a terminating operator may override the caller ID value that your end user will receive in order to improve delivery quality or follow local Telecom regulations in particular countries.

callback_url
string

If you want to receive transaction callbacks at a URL you provide, you can do so with this parameter. If you happen to have the callback URL feature enabled for your account with the URL already set, using this parameter will override whatever was set up previously. If you decide to use caller_id, you need to set up your callback URL.

account_lifecycle_event
string

This parameter allows you to indicate what phase of the lifecycle you are in when you send a transaction. The options for this parameter are -

  • create - For the creation of a new account.
  • sign-in - For when an end user signs in to their account.
  • transact - For when an end user completes a transaction within their account.
  • update - For when an update is performed, such as an update of account information or similar.
  • delete - For when an account is deleted.
originating_ip
string

Your end user’s IP Address (do not send your own IP address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.

Responses

Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.

Status Code Associated Text String Description
100 Call answered The call was answered by the end user or voicemail.
101 Not answered No one answered the call.
104 Wrong/invalid phone number The phone number is not correctly formatted in some way, so a call cannot be placed.
106 Call failed The call did not go through. Typically this occurs when TeleSign’s upstream providers fail to complete the call. Sometimes retrying will work.
107 Line busy The line was busy when the call tried to reach the end user’s device.
130 Call blocked by TeleSign TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.
Schema
object
reference_id
string

A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

status
object
code
string

This code describes the status of your transaction. You can use this to programmatically respond. You are returned two types of codes, either status codes or error codes. TeleSign recommends you code against these rather than the HTTP response status. You can read more about status codes on the All Status and Error Codes page.

required
description
string

A text description of the status code.

required
updated_on
string

This is a timestamp showing when your transaction status was updated last.

required
voice
object
user_input
string

If the end user answers a voice call and presses on the keypad after the message plays, you will see this parameter and it will display whatever the end user pressed. If the end user presses multiple digits on the keypad, only the last digit is returned. Additionally, if the end user presses the keypad before the message completes, that information will not be recorded at all.

caller_id
string

If you chose a caller id, this parameter comes back in the response and lists the caller_id that you chose.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
2 variables not set
username
password