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-ww.telesign.com/v1/voice as the base endpoint.
  • Accept only UTF-8 encoded unicode characters as inputs.

Send a Voice Message (POST)

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)

TeleSign offers the option of buying a caller ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number.

You can use the Phone Numbers API to buy a phone number. This is best if you do not need to buy numbers in areas that have special restrictions. Details about the Phone Numbers API (and what areas have restrictions) are available on the Get Started with the Phone Numbers API page.

Alternatively, you can speak with your TAM to purchase one or more phone numbers to use as a caller ID. You need at least one if you want to receive messages using Inbound SMS.

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.

NOTE:

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

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-ww.telesign.com/v1/voice HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:51p3DmaSH8oSfV0yHdAp9HNgifg=
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
{
"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 can retrieve verification results by sending a GET request message to the TeleSign web server. Here is an example GET request:

GET Request Example
GET https://rest-ww.telesign.com/v1/voice/B56A1234567C016489536C10F594029B HTTP/1.1
Authorization: Basic 444444A2-1F7E-11E1-B760-000000000000:lWizTxkdlfhiriwQiCE9FnM44TQ=

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 Body 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: