NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by contacting our experts.

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
  • Mask numbers
  • 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
  • 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.

Receiving Notifications

You will receive notifications about actions you have sent through the Voice API at a customer event URL that you control. See Customer Event URL on the Voice API Reference page for more details.

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

To learn how to make a call, play or speak a message, and collect digits from the end user who receives the call, see Stream Audio and Collect Digits.

Set up a Call with Number Masking

To learn how to connect two users in a phone call where the phone number for each user is masked, see Set Up a Call with Number Masking.

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 examples of events your server may receive during 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 actions you might send to the Voice API.

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.