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

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.

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).

The Voice web service is discussed in the following sections:

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)f-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

caller_id

  • [Optional] This parameter allows you to set a phone number as caller ID for a Voice API message sent to your end users. In order to use a specific caller ID, you must purchase a phone number from TeleSign. This can be done with your account at portal.telesign.com. Be aware that 100% preservation of a caller ID value is not guaranteed. TeleSign or a terminating operator may override the caller ID value that your end user will receive in order to improve delivery quality or follow local Telecom regulations in particular countries. Learn how to buy a number to use as caller id in the Buy a Phone Number (Caller ID) section of this page.

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. If you decide to use caller_id, you need to set up your callback URL.

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). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.
  • [Example IPv4] originating_ip=203.0.113.45
  • [Example IPv6] originating_ip=2001:db8:85a3::8a2e:370:7334
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"
   }
}

Buy a Phone Number (Caller ID)

TeleSign offers the option of buying a caller ID to use to send voice messages to your end users. A caller ID is sometimes referred to as a dedicated phone number, and in the portal (portal.telesign.com) it is referred to as a phone number. If you want to buy a phone number to use as a caller ID, do the following:

  1. Go to portal.telesign.com and log in.
  2. If you are on TeleSign's free trial, you need to upgrade and provide billing information before proceeding. You do that by clicking the Upgrade button in the upper lefthand corner. If you already upgraded your account, ignore this step.
  3. In the left nav, under Products, click Messaging.
  4. Click Settings.
  5. Next to Customer Callback URLs, click Edit. The Customer Callback URLs popup appears.
  6. Click Add a URL.
  7. Enter the URL you want to use for receiving callbacks from your end users.
  8. Click Save.
  9. On the left nav, under Account, click Phone Numbers. The Buy a Phone Number screen appears.
  10. You can search for a phone number to use as a caller ID by country and by feature using the drop downs. Use the Search by Country drop down to choose the appropriate country. Because you are going to use the phone number as a caller ID, open the Feature drop down and choose Voice.
  11. Click Search.
  12. From the list of numbers returned, choose a number you want to buy and next to it click Buy Now. If you did not set up a callback URL, you will not be able to buy a number. You must have your URL configured before buying. If your URL is configured, the Confirm Payment popup appears.
  13. Check to see that you have the correct phone number and features. Review the compliance information provided if you need to. If everything looks ok, click Submit. You get a message saying your phone number was successfully purchased.

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