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.

If you are looking for the legacy Voice API at endpoint https://rest-ww.telesign.com/v1/voice go to the Voice (Legacy) page.

Get Started with TeleSign’s Voice API

The TeleSign Voice API allows you to:

  • Make, receive and control calls
  • Collect digits (DTMF tones)
  • Connect two parties
  • Deliver secure, voice-based one-time passcodes (OTPs)
  • Stream audio
  • Use text-to-speech with broad language support
  • Anonymize phone calls
  • Build inbound and outbound Interactive Voice Response (IVR)
  • Perform cold transfers
  • Record calls

General Requirements

All requests submitted to the TeleSign Voice API must observe the following requirements:

  • Authentication: Basic (easiest to implement) or Digest
  • Base Endpoint: https://rest-ww.telesign.com/v2/voice
  • MIME Type: application/json (use JSON-RPC format)
  • Encoding: Use only UTF-8 encoded unicode characters as inputs.

Options for Receiving Notifications

You can either receive notifications at one or more customer event URLs that you control, or proactively query TeleSign to determine the status of a call or action. You can learn more about both options at Notification Service on the Voice API Reference page.

Note

If you are receiving events from TeleSign to a customer event URL, you do not need to use authentication in your responses. However, you should check that events posted to this URL by TeleSign are actually from TeleSign. This is a security best practice.

Make an Outbound Call

If you want to make an outbound call to make a phone call, or send alerts, marketing messages, notifications, or one-time pass codes (OTPs) refer to the Make an Outbound Call page.

Receive an Inbound Call

Learn how to receive inbound calls and handle them on the Receive an Inbound Call page.

Send a TTS Message and Collect Digits

You can create a custom message to be spoken using text-to-speech (TTS) and collect digits from the listener if you wish. See the Send a TTS Message and Collect Digits page for details.

Stream Audio and Collect Digits

This page shows you how to make a call, play or speak a message, and collect digits from the end user who receives the call. See the Stream Audio and Collect Digits page for more information.

Set up Anonymous 2-way Voice

If you want to get started connecting two users into a phone call where the phone number for each user is masked, see the Set up Anonymous 2-way Voice page.

Set up Click-to-Call

Click-to-call is when a user kicks off a request for a call by pressing a button in an app or on a website. If you want to learn about setting up click-to-call, check out the Set up Click-to-Call page.

Perform a Cold Transfer

A cold transfer is when you transfer a caller from one agent or automated message to another agent or automated message without any notice or introduction. You can learn about creating a cold transfer on the Perform a Cold Transfer page.

Survey After Call

The survey after call feature allows you to send your users a survey if they stay on the line after chatting with an agent, or otherwise using your IVR service. You can learn more about this feature on the Survey After Call page.

Record a Call

The call recording feature allows you to record calls, pause and resume recordings, and delete recordings. You can learn more about this feature on the Record a Call page.

Buy a Phone Number (Sender ID)

You can buy phone numbers to use with the Voice API by using the Phone Numbers API. Read more on the Phone Numbers API page.

Voice API Examples

This section provides example event and action payloads for the API. For further technical details, including definitions for each parameter, see Voice API Reference.

Event Examples

These are example events your server will receive throughout the duration of a call.

POST Request for incoming_call
{
  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
        "to": "15555551212",
        "from": "15558675309",
      }
}
Answered Event for dial
{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "answered"
  }
}
Play Completed Event
{
  "event": "play_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "playback_successful",
    "collected_digits": "923"
  }
}
Speak Completed Event
{
  "event": "speak_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "speak_successful",
    "collected_digits": "923"
  }
}
Call Completed Example
{
  "event": "call_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "to": "15558675309",
    "from": "15555551212",
    "direction": "inbound",
    "created_on_utc": "2018-08-07T20:33:38.003718",
    "answered_on_utc": "2018-08-07T20:33:40.003718",
    "ended_on_utc": "2018-08-07T20:33:44.003718",
    "status": "hangup",
    "duration": 4
  }
}

Action Examples

Here are examples of JSON responses TeleSign expects when we send you an event. This is your command.

Dial
[
  {
    "method": "dial",
    "params": {
      "to": "15555551212",
      "caller_id_number": "15554441313"
    }
  }
]
Play Action
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com"
  }
}
Play Action with Collect Digits Feature
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
      "timeout": 10000,
      "inter_digit_timeout": 3000
    }
  }
}

Next Steps

This section offers some suggestions for next steps to take.

  • Voice API Reference - See further technical detail for the API, including definitions for each parameter.