Want to provide feedback?

Write to docs@telesign.com.

Customer Action API Reference

TeleSign’s Customer Action API is an optional API that you can use with TeleSign’s Voice API. It allows you to issue actions for what to do with a call without needing to have the command triggered by an event posted to your server by TeleSign.

For more details about how the Voice API works with events and actions, refer to the Voice API pages.

General Information

All requests submitted for this API:

  • Must be authenticated with basic authentication.
  • Use https://rest-ww.telesign.com/v2/voice as the base endpoint.
  • Are formatted using JSON-RPC.
  • Accept only UTF-8 encoded unicode characters as inputs.

This API is a companion API to the TeleSign Voice API. It is intended for use if you do not want to make choices about what to do with calls by waiting for events from TeleSign to be posted to your customer event URL.

Glossary

  • Call - Connects together two or more parties to allow them to communicate with audio.
  • Events - These are posted by TeleSign to the customer URL you give TeleSign. They occur when you are using the Voice API.
  • Actions - When you want to do something with a call, you use actions to do so. In the Voice API, actions are triggered by events. In the Customer Action API, you can take action on a call without having it triggered by an event.

Authorization

You use authorization to initialize a call, and to issue requests to take action whenever you use the Customer Action API.

TeleSign’s Customer Action API uses Basic authorization. Whenever you send a request to take action, your header should include an authorization header like this:

Authorization: Basic base64encoded(customer_id:api_key)

In the final version, you would remove the base64encoded and parentheses shown in the example, they are intended to show what part of the content needs to be base64 encoded.

Customer Action API Structure

This section describes action requests and responses. Structure and available actions you can take are included.

Action Request

Using the Customer Action API, you can use the following actions:

  • dial
  • hangup
  • speak
  • record_start
  • record_stop
  • record_pause
  • record_resume

An example request looks like this:

Action Request
POST https://rest-ww.telesign.com/v2/voice 
Content-Type: application/json
Authorization: Basic base64encodedtoken
  
{
    "method": "dial",
    "params": {
        "caller_id": "15551234567",
        "to": "15555555555"
    }
}

Dial

You can use dial to place a call to a number you specify.

Dial Request Body
object
caller_id
string

The caller ID to show on the call. You must use a TeleSign caller ID. It can be purchased using the Phone Numbers API.

required
to
string

This is the destination phone number you want to connect to for the call.

required

Hangup

You can use hangup to hang up on a call.

Hangup Request Body
object
reference_id
string

Provide the reference identifier to indicate what call to operate on.

required

Speak

Use this action to create a custom message that is spoken aloud for the caller/listener using text-to-speech.

Speak Request Body
object
reference_id
string

Provide the reference identifier to indicate what call to operate on.

required
tts
object
collect_digits
object

Record Start

Use this action to begin recording a call.

object
reference_id
string

Provide the reference identifier to indicate what call to operate on.

required

Record Stop

Use this action to stop recording a call.

object
reference_id
string
required

Record Resume

Use this action to resume a recording that you paused.

object
reference_id
string

Provide the reference identifier to indicate what call to operate on.

Record Pause

Use this action to pause a recording that you started.

object
reference_id
string

Provide the reference identifier to indicate what call to operate on.

required

Action Response

For every action request you send, TeleSign responds with an asynchronous response payload immediately, that looks like this:

Asynchronous Action Response
POST https://rest-ww.telesign.com/v2/voice
Content-Type: application/json
Authorization: Basic base64encodedtoken

{
    "reference_id": "B596D7B0D1800164898350B4E71B005C",
    "status": "dial_accepted"
}
object
reference_id
string

A unique identifier that you can use to retrieve information about the call, or issue additional commands to the call with.

status
string

This is an enum string that will provide status information about the call.