Voice API - Send a TTS Message and Collect Digits

The TeleSign Voice API allows you to convert text into a voice-based message using text-to-speech (TTS). Provide a localized customer experience in any of 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 Voice API. TTS is a low cost way to create your own inbound or outbound interactive voice response (IVR).

See Supported Languages for Text-to-Speech to make sure the language you want to use is supported before following the steps below.

Before You Begin

You must have the following before sending a TTS message:

  • TeleSign credentials: Your Customer ID and API key
  • Customer event URL: A notification service you have set up 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 do not want to use your own number, you should also have:

  • TeleSign phone number: A phone number you have purchased from TeleSign to use as a caller ID. Purchase a number using the TeleSign Phone Numbers API (see Get Started with the Phone Numbers API) or ask our Customer Support Team to purchase a number for you. Make sure that the number is voice-capable (include the parameter and value voice_capable=true in your request to the Phone Numbers API). Refer to Get Started with the Phone Numbers API for more details.



For further technical details of the Voice API, 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)

  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__)

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',
            'tts': { 'message': message, 'language': language },
            'collect_digits': { 'max': max, 'timeout': timeout, 'inter_digit_timeout': inter_digit_timeout, 'terminators': terminators }

        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.

Did this page help you?