Voice API - Get Started

This page explains how to use the Voice API.

📘

NOTE

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

📘

NOTE

Go to the Voice API overview page for a list of guides for specific use cases.

General Requirements

  • Authentication: Basic (easiest to implement) or Digest
  • Endpoint: https://rest-ww.telesign.com/v2/voice
  • Accepts: application/json (use JSON-RPC format)
  • Responds With: application/json
  • Encoding: UTF-8 encoded unicode characters
  • Supported Methods: POST

🚧

CAUTION

Use only codecs and standards for audio files supported by the Voice API. See Supported Standards and Codecs for more details.

Key Terms

  • Actions: Data objects you send to TeleSign, to tell Voice what to do, usually in response to an event or to start a new call.
  • Voice API: The service you use to initiate calls with TeleSign and to send some actions.
  • Events: Data objects that TeleSign sends to you, which serve as notifications about your Voice calls and of incoming calls.
  • Webhook Endpoint: One or more services that you set up, where TeleSign can send you events. In your HTTP response to the requests with these events, you can also include additional actions for Voice.

Set Up Steps

  1. Lease a TeleSign phone number.
    See Phone Numbers API for details.
  2. Create at least one webhook endpoint.
    See Receive Events with Webhooks for detailed instructions.
  3. Set up integration to send actions to the Voice API.
    See POST /v2/voice for reference details.
  4. Map out your call flow.
    Decide on your specific use cases.
  5. Create business logic for each use case.
    Find integration details for each individual use case on the relevant how-to guide page listed on Voice API and follow those steps.
  6. Test.
  • Make an outbound call using Voice to a phone number for a test device you have access to.
  • Answer the call
  • Check for notification events about the call received by your webhook endpoint service (see Example: Test Voice Setup below).

Example: Test Voice Setup

Step 1: Send dial action

  1. Send a request to the Voice API with the dial action
POST /v2/voice HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
Content-Type: application/json
{
  "method": "dial",
  "params": {
    "to": "15555551212",
    "caller_id_number": "15554441313"
  }
}

Step 2: Receive dial_accepted response

The service processes your request and then sends a call to your test device. The service sends you an HTTP 202 ACCEPTED response, with no error strings indicating failure to process.

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
{
    "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "status": "dial_accepted",
}

Step 3: Answer the call

Your test device rings. Answer the call.

Step 4: Receive dial_completed event

Your webhook endpoint receives a notification like this:

POST /webhook_endpoint HTTP/1.1
Host: your-webhook-service.com
Content-Type: application/json
{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "from": "15554441313",
    "to": "15555551212",
    "status": "answered"
  }
}

Step 5: Respond with hang_up action

In your HTTP response to TeleSign's request in the previous step, include the hang_up action.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "method": "hangup"
}

Step 6: The call ends

The call on your test device hangs up.

Step 7: Receive call_completed event

Your webhook endpoint receives a notification like this:

POST /webhook_endpoint HTTP/1.1
Host: your-webhook-service.com
Content-Type: application/json
{
  "event": "call_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "to": "15555551212",
    "from": "15554441313",
    "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": 1,
    "session_info": {}
  }
}

Did this page help you?