Voice - Make an outbound call

📘

NOTE:

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

This page explains how to use Telesign Voice to make outbound calls.

Common use cases

Some common use cases for these calls are:

• Alerts, reminders, and notifications
• Marketing messages
• One-time passcodes (OTPs) for verification
• Setting up outbound IVR

📘

NOTE

Telesign calls have a maximum call duration of four hours.

Requirements

You must have the following:

• Telesign authentication credentials: Your Customer ID and API key.
• 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.
• 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.

Be sure also to only use supported standards and codecs (see Voice - Supported standards and codecs).

How to make the call

Follow these steps to make an outbound call.

Step 1: Dial

Send the dial Action to Telesign Voice.

Include these required parameters with your Action:

• to – Include the destination phone number here.
• caller_id_number – Include a Telesign phone number here

Dial with extension

Include this optional parameter if desired:

• send_dtmf – Include digits to add into the call after it connects. Common use cases for this feature are to enter an extension or a conference code.

📘

NOTE

Full technical details for the dial action can be found on Voice - Actions.

Example:

Here is an example of making an outbound call using Python:

make_outbound_call.py

import base64
import requests
import os

# Replace the defaults below with your Telesign authentication credentials from https://teleportal.telesign.com
customer_id = os.getenv('CUSTOMER_ID', 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890')
api_key = os.getenv('API_KEY', 'ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==')

# Set the REST API URL
url = "https://rest-ww.telesign.com/v2/voice"

# Set the API inputs.
destination_number = os.getenv('PHONE_NUMBER', '15554441313') # The complete phone number you want to call, including country code, with no special characters or spaces.
caller_id_number = os.getenv('SENDER_ID', '15555551212') # The phone number you purchased from Telesign.
external_id = '4142b474-d65d-4265-a5fa-a581b1fe6101' # An external ID you generated for this transaction. Optional parameter.
send_dtmf = '8' # Digits to add into the call. Optional parameter.

# Generate auth string.
auth_string = ":".join([customer_id, api_key]).encode()
auth_string = " ".join(["Basic", base64.b64encode(auth_string).decode("utf-8")])

# Create the request body.
payload = {
  "method": "dial",
  "params": {
    "to": destination_number,
    "caller_id_number": caller_id_number,
    "external_id": external_id,
    "send_dtmf": send_dtmf
  }
}

# Create the request headers.
headers = {
  'Accept': "application/json",
  'Content-Type': "application/json",
  'Authorization': auth_string
}

# Make the request and capture the response.
response = requests.post(url, headers=headers, json=payload)

# Display the response for debugging purposes.
print(f"\nResponse:\n{response.status_code}\n")

Step 2: React to dial response

Depending on what Telesign tells you about the status of the dial in the response Event (for example that the end user hung up or answered the call), you might be able to send another Action at this point. For example, if the call is answered you can send one of the following Actions:

• play – Play a recorded message for the end user.
• speak – Use text-to-speech (TTS) to deliver a custom message in the language of your choice.
• send_dtmf – Enter DTMF digits programmatically into the call.

Possible call flows

Figure 1 shows you some of the ways an outbound call could go. The arrows with dotted lines represent asynchronous responses. The labeling of steps 6-9 with a letter (such as 6A, 6B, 6C) show you three different ways an outbound call could complete.

Call flow A: Call accepted

The call is accepted and you choose to play a recorded message or send a text-to-speech message in response.

1. You send a dial Action to Telesign.
2. Telesign calls the destination_number parameter.
3. Telesign sends an Event indicating that your dial request was accepted.
4. The end user's device notifies Telesign that the call was answered.
5. Telesign sends an Event indicating that the dial completed and the call was answered.
6. ( A ) You send an Action asking that Telesign play a message or use text-to-speech to speak a message (this may include requesting that digits be collected).
7. ( A ) Telesign plays or speaks your message for the end user.
8. ( A ) The end user's device notifies Telesign that the message finished playing.
9. ( A ) Telesign sends you and Event indicating that the play message or play recording task completed.

Call flow B: You terminate

You choose to terminate the call without playing or speaking a message.

1. You send the dial Action to Telesign.
2. Telesign calls the number you specified.
3. Telesign sends an Event indicating that your dial request was accepted.
4. The end user's device notifies Telesign that the call was answered.
5. Telesign sends an Event indicating that the dial completed and the call was answered.
6. ( B ) You send an Action requesting that Telesign hang up.
7. ( B ) Telesign sends you an Event indicating that the call is completed.

Call flow C: End user terminates

The end user hangs up the call before the audio finishes playing.

1. You send the dial Action to Telesign.
2. Telesign calls the number you specified.
3. Telesign sends an Event indicating that your dial request was accepted.
4. The end user's device notifies Telesign that the call was answered.
5. Telesign sends an Event indicating that the dial completed and the call was answered.
6. ( C ) You send an Action requesting that Telesign play a message or use text-to-speech to speak a message (this may include requesting that digits be collected)
7. ( C ) Telesign plays or speaks your message for the end user.
8. ( C ) The end user hangs up during the call.
9. ( C ) Telesign sends you an Event indicating that the call is completed.