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:
The end user’s phone number with country code included. Avoid use of special characters and spaces.
Text of the message to be converted to speech and sent to the end user. You are limited to 1600 characters.
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)
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-
|Chinese (Hong Kong, Cantonese)||f-zh-HK|
|Spanish (Spain, Castilian)||f-es-ES|
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.
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.
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.
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.
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.
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.
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.
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.
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.
You can mark each of your requests with your own identifier. This identifier is returned as part of a delivery receipt (DLR) callback.
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.
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.|
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.
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.
A text description of the status code.
This is a timestamp showing when your transaction status was updated last.
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.
If you chose a caller id, this parameter comes back in the response and lists the caller_id that you chose.