Voice - Get started

📘

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.

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 Voice. See Voice - 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.
• Engage API (Voice): 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.
   Contact our Customer Support Team for details.
2. Create at least one webhook endpoint.
   See Voice - Receive Events with webhooks for detailed instructions.
3. Set up integration to send actions to the Engage 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 - Overview 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 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",
    "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101"
  }
}

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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101"
}

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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "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": {}
  }
}