Get Started with the Voice API

TeleSign’s Voice API is a REST API that allows you to easily send voice messages. You can send alerts, reminders, and notifications, or you can send verification messages containing time-based one-time passcodes (TOTP).

This page provides instructions and references for features of the Voice API.

General Information

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.

Send a Voice Message

For quick instructions about how to send your first voice message, see the Send a Voice Message page.

For a list of available parameters, refer to:

Obtain Transaction Status Results

You can find out the status of your transactions two ways:

  • Status Request - quickly get the status of a transaction with a GET request.
  • Transaction Callback - TeleSign uses a POST request to post status information about your transactions to a URL that you provide. (Recommended for high volume transactions.)

Read more about these options on the Obtain Transaction Status Results page.

Buy a Phone Number (Caller ID)

If you need to buy a phone number for use as a caller ID, refer to Buy a Phone Number (Sender/Caller ID).

Text-to-Speech Hints

When making a voice call, you can choose to have a text-to-speech (TTS) translation of a text message to speech, instead of using TeleSign’s default message. To use the TTS feature, use the voice parameter in your request.

All TeleSign TTS voices are female. Most generic text will be spoken as expected, with pauses for commas, semicolons, dashes, and at the end of a sentence. You can create a longer pause between words by using a newline character ( “\n” ). Depending on what language you are coding in, you will need to create the newline character as appropriate. For example, if you are using Python, “\n” is correct. For a shorter pause, use a colon ( “:” ) or semicolon ( “;” ).

NOTE:

The TTS parameter allows UTF-8 strings, therefore it can accept Unicode characters.

Handling Strings That Are Not Words

Strings sent to the TTS engine outside of typical words found in the dictionary, such as URLs, email addresses and company names, may be fully pronounced, spelled out, or a combination of the two. Be aware that while TTS is great for spoken text, it can be tricky when you are using non words or auto-generated words like company names. The system does what it can to pronounce all words, but this is dependent on how close a word is to one found in the dictionary. Even made up words can be interpreted if they resemble a word in the dictionary. Pronunciation becomes less predictable the further something is from available dictionary words.

The only reliable way to know that you are producing speech that sounds the way you want to is to generate a test call with the string in the language you want to use. Listening, ideally by a native speaker, is the best way to troubleshoot this feature.

Optimizing Pauses Between Words and Numbers

This section describes how pauses work in the system. Information is tailored to English and may be slightly different for other languages.

No Spaces

If you write a number out with no spaces, for example “12345”, it is read aloud digit by digit in a natural sounding way “one, two, three, four, five”.

Spaces

Spaces create a small pause when a number is being read. “1 2 3 4 5” sounds similar to “12345”.

Semi-Colons

Semi-colons are the most reliable way to include a space between pronounced words and numbers. “1;2;3;4;5” will create a longer pause between each digit than just adding spaces.

Commas

If you write a number using a comma, for example “12,345” then it will be spoken as “twelve thousand three hundred forty five” rather than each individual number being called out. If you move the comma around, for example “123,45”, the system would read this as “one hundred twenty three (pause) forty five”, and for “1234,5” it would be pronounced twelve thirty four (pause) five". This differs by language. For example, in French, the comma is read out.

Newline

A long pause can also be included by adding a newline in the message. How you write a newline differs by language. Python ( “\n” ) is used for the examples here. For example, if you write “1;2;3\n4;5;6”, the TTS engine would pronounce the first group of three digits with a small pause between each digit, then a long pause for the newline (\n) and then pronounce the second group of three digits with a small pause between each.

Dashes

Dashes are sometimes silent and sometimes spoken aloud, often as “hyphen”. For phone numbers, for example “1-559-555-5643”, the number might be read digit by digit, or the dashes could be read aloud, and sometimes the last four digits are read out like so: “five thousand six hundred and forty three”. You will need to test for your language.

Other Punctuation

Generally, other punctuation is not read aloud, but may create a pause. Test to be sure.

Voice API Examples

This section provides examples of a request and response using the Voice API.

POST Request and Response Examples

You use a POST request to send your voice message.

POST Request Example
POST https://rest-api.telesign.com/v1/voice HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/x-www-form-urlencoded

phone_number=15555551212&message=Your message here.&account_lifecycle_event=create&originating_ip=203.0.113.45

Here is an example response to your POST request:

POST Response Body Example
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"status": {
   "updated_on": "2017-02-28T19:02:31Z",
   "code": 103,
   "description": "Call in progress",   
 },
"voice": "f-en-GB",
}

GET Request and Response Examples

You use a GET request to find out the status of a voice transaction.

Example GET Request with the Voice API
GET https://rest-api.telesign.com/v1/voice/B56A1234567C016489536C10F594029B HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=

You can retrieve verification results by sending a GET request message to the TeleSign web server. The response body contains a JSON object with members described below:

GET Response Example
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"status": {
   "code": 100,
   "description": "Call answered",
   "updated_on": "2017-02-28T19:02:31Z",
   },
"voice": {
   "caller_id": "15555551212",
   "user_input": "3"
   }
}

Compliance

For Compliance information, please see the Voice section of the Compliance page.

Next Steps

This section offers some suggestions for next steps to take.