Want to provide feedback?

Write to docs@telesign.com.

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by navigating to our Voice API signup page.

Send a TTS Message and Collect Digits

TeleSign’s Voice API allows you to convert text into a voice-based message using text-to-speech (TTS). Provide a localized customer experience with TTS available in 26 languages and dialects.

You can use TTS as part of an outbound call, or you can receive an inbound call and play a TTS message. You can combine this with collecting digits, or any other features offered by the TeleSign Voice API. TTS is a low cost way to create your own inbound or outbound interactive voice response (IVR).

Requirements

You must have the following:

  • TeleSign credentials - your customer ID and API key
  • Access to the Voice API
  • Caller ID if you do not want to use your own number. For details about purchasing a phone number for use as a caller ID, refer to the Get Started with TeleSign’s Phone Numbers API
  • For details about supported standards and codecs, see the Supported Standards and Codecs.
  • If you plan to use events posted by TeleSign as a trigger for what action to take next with a call, you need a customer event URL on your server for TeleSign to post event information to. For more details, refer to the Set up the Customer Event URL section on the Voice API Reference page.
  • If you want to make a choice about how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:
Note

For further technical details, including definitions for each parameter, see Voice API Reference.

Implement a Message with TTS

This section walks you through dialing a number, playing a text-to-speech (TTS) message, and collecting digits from an end user. You could also begin this process by reciving an inbound call, then playing a TTS message and collecting digits. Collecting digits is optional. These are just a few of the possible user flows. If you want to see how to start with an inbound call, see Receive an Inbound Call.

To set up the call, do the following:

  1. You create an outbound call using the dial action. You add a destination phone number for to and your callerID (phone number you bought from TeleSign) goes in the caller_id_number field if you decide to use a caller ID (recommended). If you reviewed the Make an Outbound Call page, this will look familiar.
Outbound Call with Python
from base64 import b64encode

import requests

customer_id = 'Your customer ID goes here.'
api_key = 'Your API key goes here.'

destination_number = 'The complete phone number you want to call, including country code, with no special characters or spaces.'
caller_id_number = 'The phone number you purchased from TeleSign goes here.'

url = "https://rest-ww.telesign.com/v2/voice"

payload = {
  "jsonrpc": "2.0",
  "method": "dial",
  "params": {
    "to": destination_number,
    "caller_id_number": caller_id_number
  }
}


headers = {
  'Accept': "application/json",
  'Content-Type': "application/json",
  'Authorization': "Basic {}".format(b64encode(customer_id + ":" + api_key).decode('utf-8'))
}

response = requests.request("POST", url, data=json.dumps(payload), headers=headers)

print(response.text)
  1. TeleSign notifies you with a dial_completed event. You should have some code to check the status is answered.

  2. If everything looks good, you will want to move ahead and respond to the answered event with the speak action to play a custom TTS message and collect digits. You can either send a plain text message or use speech synthesis markup language (SSML). For more details on SSML tags that we support, see Using SSML for TTS. Here is a sample of how the JSON you send in your request might look:

Example JSON for TTS and Collect Digits
{
  "jsonrpc": "2.0",
  "method": "speak",
  "params": {
    "tts": {
      "message": "<speak>Press <prosody volume='loud'>1</prosody> for your account balance. Press <prosody volume='loud'>2</prosody> to speak with a customer service representative.</speak>",
      "language": "en-US",
      "type": "ssml"
    },
    "collect_digits": {
      "max": 1,
      "timeout": 10000,
      "inter_digit_timeout": 3000,
      "terminators": "*"
    }
  }
}

Here is a code sample showing how you might handle TeleSign event information:

TTS and Collect Digits in Python
from json import dumps, loads

from bottle import route, run, request, post

# This is a an example response to a dial_completed event that will play a message and collect digits during play.
# {
#     "jsonrpc": "2.0",
#     "method": "speak",
#     "params": {
#     "tts": {
#				"message": "Press 1 for your account balance. Press 2 to speak with a customer service 
# representative",
#				"language": "en-US"
# }, 
#    "collect_digits": {
#    		"max": 1,,
#    		"timeout": 10000,
#    		"inter_digit_timeout": 3000,
#				"terminators": "*"
#   }
#  }
# }

class Response:

    def __init__(self, method, params=None):
        if params is None:
            params = {}

        self.json_rpc = "2.0"
        self.method = method
        self.params = params

    def to_json(self):
        return dumps(self.__dict__)

@post('/')
def telesign_event():
    # Throughout a call session TeleSign will notify you of all events.
    # Each event requires you to send us an appropriate action defined in our documentation.
    # This endpoint needs to match the URL stored in our system to properly communicate.
    #
    # In this example, the server will respond to the dial_completed event.

    # First extract the event from the JSON body in the request.
    event = request.json.get('event')

    if event == 'dial_completed':
        # Check for an 'answered' status. For 'answered' fill out your parameters:
        message = "Press 1 for your account balance. Press 2 to speak with a customer service representative."
        language = "en-US" 
        max = 1
        timeout = 10000 # How long to wait for the first digit before ending collection. 
        inter_digit_timeout = 3000 # How long to wait for the next digit before ending collection, after at least one digit has been entered. 
        terminators = "*" # The characters to use as terminators for end user entry of digits.

        # Generate the command in the JSON format used by TeleSign.
        return Response(method='speak',
          params={
            'tts': { 'message': message, 'language': language },
            'collect_digits': { 'max': max, 'timeout': timeout, 'inter_digit_timeout': inter_digit_timeout, 'terminators': terminators }
          }
       	).to_json()
    else:

        return Response(method='hangup').to_json()

run(host='localhost', port=8080, debug=True)
  1. If speaking the message and collecting digits is successful, you get back speak_completed in the response from TeleSign. You can issue a request to hangup the call with hangup or you can send further messages with play or speak commands.

Supported Languages for Text-to-Speech

Some text-to-speech voices are male and some are female. What TeleSign offers is noted next to each language.

Language TTS Tag Male Voice Female Voice
Arabic arb x
Chinese, Mandarin cmn-CN x
Danish da-DK x
Dutch nl-NL x
English, Australian en-AU x
English, British en-GB x
English, Indian en-IN x
English, US en-US x
English, Welsh en-GB-WLS x
French fr-FR x
French Canadian fr-CA x
German de-DE x
Hindi hi-IN x
Icelandic is-IS x
Italian it-IT x
Japanese ja-JP x
Korean ko-KR x
Norwegian nb-NO x
Polish pl-PL x
Portuguese, Brazilian pt-BR x
Portuguese, European pt-PT x
Romanian ro-RO x
Russian ru-RU x
Spanish, European es-ES x
Spanish, Mexican es-MX x
Spanish, US es-US x
Swedish sv-SE x
Turkish tr-TR x
Welsh cy-GB x

Next Steps

This section offers some suggestions for next steps to take.