TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Standard Voice API

TeleSign's Voice API is a REST API that allows you to easily send voice messages. You can send alerts, reminders, and notifications, or you can send verification messages containing time-based one-time passcodes (TOTP).

READ THIS NOTE:

This documentation is intended for you if you use the Standard versions of TeleSign products. If you are using TeleSign's free trial, you are using Standard TeleSign products.

You use Standard TeleSign products if you log in to your account at portal.telesign.com, use
endpoints that begin with rest-api.telesign.com, and do not have a designated Technical Account Manager (TAM).

If you log in to your account at teleportal.telesign.com, have endpoints that begin with rest.telesign.com or rest-ww.telesign.com, and have a TAM, you need the Voice API for Enterprise page instead.

Implement the Voice API with an SDK

TeleSign recommends using one of the SDKs as the SDKs handle authentication for you and are available in Java, Python, Ruby, PHP, and C#.

The following quick starts can help you get started quickly with the Voice API:

Additionally, you should review the Request Parameters section and the Response Parameters section, which contains details about the parameters you can include in requests, as well as what parameters are returned in responses.

Authentication

Access to TeleSign web services is restricted. To receive results for any call you make to a TeleSign web service, you must digitally sign your request message with valid credentials. You sign a request by creating a signature and adding it to your message’s Authorization header. The signature is your message authentication code (MAC). When received by TeleSign, the shared secret API key is used to hash details about the message. A successful match results in successful authentication and a response from the TeleSign web service you called.

To get started, you should review the basic steps for setting up authentication. Review the following:

Additionally, for an example of how to implement authentication, you can take a look at how TeleSign does it for the SDKs. Click the link for the appropriate language to see how TeleSign implements authentication.

URI

To use the Voice web service to send a request, send requests to the following URI:

https://rest-api.telesign.com/v1/voice

Supported HTTP Methods

The Voice API supports POST and GET HTTP methods.

POST

When you send a POST request with the end user's phone number to the v1/voice subresource, TeleSign sends a text to speech version of the message you specify.

GET

You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent. The URI looks like this: rest-api.telesign.com/v1/voice/<reference_id>. TeleSign returns a response message containing the results in the form of a verify JSON object in the entity body. You can read more about the reference_id parameter in the GET Request section.

Request Parameters

POST Request

The following parameters are supported in the body of a POST request:

phone_number

  • [Required] The end user's phone number with country code included.
    Example: phone_number=13105551212.

message

  • [Required] Text of the message to be converted to a voice message and sent to the end user. You are limited to 2000 code points.

message_type

  • [Required] This parameter specifies the traffic type being sent in the message. You can provide one of the following values:
    • OTP - One time passwords
    • ARN - Alerts, reminders, and notifications
    • MKT - Marketing traffic

voice

  • [Optional] The voice parameter allows you to specify a voice to be used to speak your text to speech message. If you do not specify a voice, the default f-en-US is used. At this time, all TeleSign voices are female. Available options for this parameter include:
  • LanguageLanguage Tag
    Chinese (Hong Kong, Cantonese)f-zh-HK
    Chinese (Mandarin)f-zh-CN
    Chinese (Taiwan)f-zh-TW
    Danishf-da-DK
    Dutchf-nl-NL
    English (Australian)f-en-AU
    English (UK)en-GB
    English (US)f-en-US
    English (Canadian)f-en-CA
    English (India)f-en-IN
    Finnishf-fi-FI
    Frenchf-fr-FR
    French (Canadian)f-fr-CA
    Germanf-de-DE
    Italianf-it-IT
    Japanesef-ja-JP
    Koreanf-ko-KR
    Norweiganf-nb-NO
    Polishf-pl-PL
    Portuguese (Brazil)f-pt-BR
    Portuguese (Europe)f-pt-PT
    Russianf-ru-RU
    Spanish (Mexico)f-es-MX
    Spanish (Spain, Castilian)f-es-ES
    Spanish (Catalan)f-ca-ES
    Swedishf-sv-SE

callback_url

  • [Optional] If you want to receive transaction callbacks at a URL you provide, you can do so with this parameter. If you happen to have the callback URL feature enabled for your account with the URL already set, using this parameter will override whatever was set previously.

account_lifecycle_event

  • [Optional] This parameter allows you to indicate what phase of the lifecycle you are in when you send a transaction. The options for this parameter are:
    • create - For the creation of a new account.
    • sign-in - For when an end user signs in to their account.
    • transact - For when an end user completes a transaction within their account.
    • update - For when an update is performed, such as an update of account information or similar.
    • delete - For when an account is deleted.

originating_ip

  • [Optional] Your end user’s IP Address (do not send your own IP address). This value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Textual Representation of IPv4 and IPv6 Addresses.
  • [Example] originating_ip=203.0.113.45
POST https://rest-api.telesign.com/v1/voice HTTP/1.1
X-TS-AUth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:51p3DmaSH8oSfV0yHdAp9HNgifg=
Date: Tue, 28 Feb 2017 11:02:31 GMT
Content-Type: application/x-www-form-urlencoded

phone_number=15555551212&message=Your message here.&account_lifecycle_event=create&originating_ip=203.0.113.45

GET Request

The following parameters are supported in the body of a GET request:

reference_id

  • The reference_id for the transaction you want to find out the status for.
GET https://rest-api.telesign.com/v1/voice/B56A1234567C016489536C10F594029B HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 444444A2-1F7E-11E1-B760-000000000000:lWizTxkdlfhiriwQiCE9FnM44TQ=
Date: Tue, 28 Feb 2017 11:03:33 GMT

Response Parameters

POST Response

A POST response contains the following parameters:

reference_id

  • A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

voice

  • The voice tag you selected for language appears here. If you did not use this parameter, the default f-en-US is displayed.

status

  • An object that describes the status of your transaction; it contains the following parameters:

    code

    description

    • A text description of the status code.

    updated_on

    • This is a timestamp showing when your transaction status was updated last.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"status": {
   "updated_on": "2017-02-28T19:02:31Z",
   "code": 103,
   "description": "Call in progress",   
 },
"voice": "f-en-GB",
}

GET Response

You can retrieve verification results by sending a GET request message to the TeleSign web server. The response body contains a JSON object with members described below:

reference_id

  • A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following the web service request.

status

  • An object that describes the status of your transaction; it contains the following parameters:

    code

    description

    • A text description of the status code.

    updated_on

    • This is a timestamp showing when your transaction status was updated last.

voice

    user_input

    • If the end user answers a voice call and presses on the keypad after the message plays, you will see this parameter and it will display whatever the end user pressed. If the end user presses multiple digits on the keypad, only the last digit is returned. Additionally, if the end user presses the keypad before the message completes, that information will not be recorded at all.
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"status": {
   "code": 100,
   "description": "Call answered",
   "updated_on": "2017-02-28T19:02:31Z",
   },
"voice": {
   "user_input": "3"
   }
}

Obtain Transaction Status Results

You can find out the status of your transactions two ways:

GET Request

You can find out the status of a specific transaction by sending a GET request that includes the reference ID (use the reference_id parameter) for the transaction. See the GET section for an example.

Transaction Callback

Delivery results can be obtained by using the Transaction Callback service (ideal for high volumes of transactions). You provide TeleSign with a URL, and TeleSign posts the results of your transactions to the specified URL. You specify the URL using the callback_url parameter.

Set up the Transaction Callback Service

To set up the callback service, you do the following:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign.
  2. Provide TeleSign with your private URI using the callback_url parameter.
  3. You will receive callback notifications after a transaction completes.
  4. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server waits 10 seconds, then tries again. If the second attempt fails, the server waits an additional 30 seconds and then makes a final attempt.

Request Headers

Headers

This section provides a summary of required and optional headers for a request. For details about how to use them for proper authentication, review the Authentication page. For more details about these headers, review the section Standard and TeleSign Specific Headers on the Authentication page.

General Headers

  • Content-Type - Required for POST requests. Ignored for GET requests, but you must mark its position with a newline for StringToSign.
  • Date - Required unless you include X-TS-Date. If you do not include the Date header value, you must mark its position with a newline character for StringToSign.

Request Headers

TeleSign-Specific HTTP Headers

  • X-TS-Date - Optional, you may use this instead of the Date header.
  • X-TS-Nonce - Optional, specifies a unique, random nonce string. You can include this header to provide additional protection against malicious replay attacks
  • X-TS-Auth-Method - Required for HMAC-SHA256.

Response Headers

Allow

  • Indicates the HTTP methods that the resource supports. The allowed methods for v1/voice are POST and GET.

Content-Type

  • Indicates the content type of the entity-body transferred in the response message. TeleSign web services always use a value of application/json.

Examples

This section compiles all the examples throughout this page into one section.

POST https://rest-api.telesign.com/v1/voice HTTP/1.1
X-TS-AUth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:51p3DmaSH8oSfV0yHdAp9HNgifg=
Date: Tue, 28 Feb 2017 11:02:31 GMT
Content-Type: application/x-www-form-urlencoded

phone_number=15555551212&message=Your message here.&message_type=OTP
GET https://rest-api.telesign.com/v1/voice/B56A1234567C016489536C10F594029B HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 444444A2-1F7E-11E1-B760-000000000000:lWizTxkdlfhiriwQiCE9FnM44TQ=
Date: Tue, 28 Feb 2017 11:03:33 GMT
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"status": {
   "updated_on": "2017-02-28T19:02:31Z",
   "code": 103,
   "description": "Call in progress",   
 },
"voice": "f-en-GB",
}
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"submit_timestamp": "Wed, 06 Nov 2015 13:36:07 GMT",
"status": {
   "updated_on": "Wed, 06 Nov 2015 13:36:11 GMT",
   "code": 100,
   "description": "Call answered",
   },
"voice": {
   "user_input": "3"
   }
}

Success Status Codes for /v1/voice

These status codes are given as a response to requests from the /v1/voice/.

HTTP Code
Status Code
Associated Text String

201

103

Call in progress

The call is in progress.

200

104

Wrong/invalid phone number

The phone number is not correctly formatted in some way, so a call cannot be placed.

200

130

Call blocked by TeleSign

TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.

Success Status Codes for /v1/voice/<reference_id>

These status codes are given as a response to requests from the /v1/voice/<reference_id> endpoint.

HTTP Code
Status Code
Associated Text String
Description

200

100

Call answered

The call was answered by the end user or voicemail.

200

101

Not answered

No one answered the call.

200

103

Call in progress

The call is currently happening.

200

104

Wrong/invalid phone number

The phone number is not correctly formatted in some way, so a call cannot be placed.

200

106

Call failed

The call did not go through. Typically this occurs when TeleSign's upstream providers fail to complete the call. Sometimes retrying will work.

200

107

Line busy

The line was busy when the call tried to reach the end user's device.

200

130

Call blocked by TeleSign

TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.

HTTP Codes Mapped to Error Codes

For a general list of HTTP codes and how they map to error codes generated by the Voice API, review the HTTP Codes Mapped to Error Codes section on the Codes, Languages, Time Zones page. These codes are returned for the code parameter if your transaction had issues.

Compliance

For voice compliance best practices, please refer to the Voice Compliance page.

Standard Voice API