Voice - Send a TTS message and collect digits

📘
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

Telesign Voice enables 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, answer it, and play a TTS message.

Before you begin

You must have the following before sending a TTS message:

Telesign authentication credentials: Your Customer ID and API key.
Customer event URL: A notification service you have set up for Telesign to post Event notifications to. See Voice - Receive Events with webhooks for instructions on how to set that up.
Supported standards and phone number formats: Verify that the standards and phone number formats that you want to use are supported by Telesign before following the steps below. See Voice - Supported standards and codecs.

📘
NOTE:
Be sure that you are using the correct language table. See this list of other language tables for Voice and Voice Verify.

If you do not want to use your own number, you should also have:

Telesign phone number: A voice-capable phone number you have purchased from Telesign to use as a caller ID. Contact our Customer Support Team for details.

📘
NOTE:
For full API reference details for this service, including definitions for each parameter, see POST https://rest-ww.telesign.com/v2/voice.

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.

To set up the call, do the following:

Create an outbound call using the dial Action. You add a destination phone number for to and your caller ID (phone number you bought from Telesign) goes in the caller_id_number field. You can add other optional parameters.

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.'
external_id = 'An external ID you generated for this transaction.' # Optional parameter

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

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


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)

Telesign notifies you with a dial_completed Event. Check that the value of the data.status property in the Event is answered.
If everything looks good, respond to the dial_completed 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 Voice - Use SSML for TTS.

Example Speak Action

{
  "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 Events:

TTS and Collect Digits in Python

from json import dumps, loads

from bottle import route, run, request, post

# This is an example response to a dial_completed event that will play a message and collect digits during play.
# {
#     "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)

If speaking the message and collecting digits is successful, you get back speak_completed in an Event from Telesign. You can send an Action to hangup the call with hangup or you can send further messages with play or speak Actions.

📘NOTE:

Before you begin

📘NOTE:

📘NOTE:

Implement a message with TTS

📘
NOTE:

📘
NOTE:

📘
NOTE: