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 Messaging API

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

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 Messaging API for Enterprise page instead.

Implement the Messaging API with an SDK

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

The following Quick Start documents can help you get started with the Messaging 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 handle 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 Messaging web service to send a request, send requests to the following URI:

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

Supported HTTP Methods

The Messaging API supports POST and GET HTTP methods.

POST

When you send a POST request with the end user's phone number to the messaging subresource, TeleSign sends the SMS 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/messaging/<reference_id>. TeleSign returns a response message in the form of a JSON object in the entity body.

Request Parameters

POST

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 sent to the end user. You are limited to 1600 characters. If you send a very long message, TeleSign splits your message into separate parts. TeleSign recommends against sending messages that require multiple SMSes when possible.

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

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.

sender_id

  • [Optional] This parameter allows you to set a specific Sender ID to be used on an SMS message sent to the end user. In order to use a specific sender ID, TeleSign must whitelist your selected sender ID values. Be aware that 100% preservation of a sender ID value is not guaranteed. TeleSign may override the sender ID value that your end user will receive in order to improve delivery quality or follow SMS regulations in particular countries. In order to use this feature, you must contact TeleSign Support and have them enable it for you.

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/messaging HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 59

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

GET

A GET request is used to find out the status of an SMS transaction. 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/messaging/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Date: Tue, 31 Jan 2017 14:53:11 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.

status

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

    code

    • This code describes the status of your transaction. You can use this code to programmatically respond. You are returned two types of codes, either status codes or error codes. You can read more about status codes in section Status Codes. You can read more about error codes in section HTTP Codes Mapped to Error Codes.

    description

    • A text description of the status code.

    updated_on

    • This is a timestamp showing when your transaction status was updated last.
{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "status": {
      "code": 290,
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "description": "Message in progress"
   }
}

GET Response

You can retrieve information about a message you sent by sending a GET request message to the TeleSign web server containing the reference ID (reference_id) for the message you want information about. 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

    • This code describes the status of your transaction. You can use this code to programmatically respond. You can read more about status codes in section Status Codes. You can read more about error codes in section HTTP Codes Mapped to Error Codes.

    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",
"submit_timestamp": "Tue, 31 Jan 2017 13:36:07 GMT",
"status": {
   "code": 290,
   "updated_on": "Tue, 31 Jan 2017 13:36:11 GMT",
   "description": "Message in progress"
   }
}

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/messaging 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.
HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST
Content-Type: application/json

Examples

POST https://rest-api.telesign.com/v1/messaging HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 59

phone_number=15555551234&message=Your message here.&account_lifecycle_event=create&originating_ip=203.0.113.45
GET https://rest-api.telesign.com/v1/messaging/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Date: Tue, 31 Jan 2017 14:53:11 GMT
HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST
Content-Type: application/json
{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "status": {
      "code": 290,
      "updated_on": "2017-31-03T14:51:28.709526Z",
      "description": "Message in progress"
   },
}
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"submit_timestamp": "Tue, 31 Jan 2017 13:36:07 GMT",
"status": {
   "code": 290,
   "updated_on": "Tue, 31 Jan 2017 13:36:11 GMT",
   "description": "Message in progress"
   }
}

URL Shortener

To help shorten your text messages, TeleSign provides a complimentary URL shortening service. You can read more about how to enable it here: URL Shortener.

Status Codes

For the Messaging API, the following codes can be returned for the code parameter. If an item says "final" that means it is a status that does not change. If an item says "intermediate" that means the transaction could resolve to another status code.

Status Code
Associated Text String
Description

200

Delivered to handset

The SMS was delivered to the end user's phone. (Final)

203

Delivered to gateway

The SMS was delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated. (Intermediate)

207

Error delivering SMS to handset (reason unknown)

The SMS could not be delivered to the end user's handset for an unknown reason. (Final)

210

Temporary phone error

The SMS could not be delivered to the handset due to a temporary error with the phone. Examples: phone is turned off, not enough memory to store the message. (Final)

211

Permanent phone error

The SMS could not be delivered to the handset due to a permanent error with the phone. For example, the phone is incompatible with SMS, or the phone is illegally registered on the network. This can happen when a phone number is blacklisted, or is incorrectly provisioned. (Final)

220

Gateway/network cannot route message

The network cannot route the message to the handset. (Final)

221

Message expired before delivery

The message was queued by the mobile provider and timed out before it could be delivered to the handset. (Final)

222

SMS not supported

SMS is not supported by this phone, carrier, plan, or user.

230

Message blocked by TeleSign

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

231

Invalid/unsupported message content

The content of the message is not supported.

237

Message blocked in requested country

You requested that messages in a specific country be blocked, and the message was being sent to this country.

238

Destination blocked by prefix

You requested that phone numbers with a particular prefix be blocked.

250

Final status unknown

The final status of the SMS cannot be determined.

286

Transaction not attempted

The SMS is blocked from being sent due to the phone type not being one of the following: mobile, prepaid, personal, or pager.

290

Message in progress

The message is being sent to the SMS gateway.

291

Queued by TeleSign

TeleSign is experiencing an unusually high volume and has queued the SMS message.

292

Queued by gateway

The SMS gateway has queued the message.

295

Status delayed

The status of the SMS is temporarily unavailable.

500

Transaction not attempted

No SMS request was attempted.

502

Campaign error

This error can be generated if there is a problem with the short code used.

503

Carrier rejected - temporary problem

This error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.

504

Carrier rejected - permanent error

This error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.

505

Error on gateway - temporary error

This error is generated if there is an error on TeleSign's partner side that is considered temporary and the message can be retried.

506

Error on gateway - permanent error

This error is generated if there is an error on TeleSign's partner side that is considered permanent and the message should not be retried.

507

Invalid destination address

There is a problem with the destination address used. Either the format is not valid, or the number is not associated with any carrier, or if MSC is used it does not know about this MSISDN.

508

Invalid source address

The message requires a source address. Verify that one is provided and correct.

509

Parameters problem

One or more parameters used in the request is not supported.

510

Message blocked by subscriber action or request

The end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.

511

Subscriber low on credit

The end user exceeded their spending limits and cannot receive SMS.

512

Roaming error

End user cannot receive SMS because their device that receives the messages is roaming.

513

Mobile number portability error

SMS failed because ported combinations are unreachable.

514

Subscriber absent

Subscriber is absent for a period of time.

515

Suspected spam

This message is considered to be spam by carrier or operator.

599

Status not available

The system is unable to provide status at this time.

HTTP Codes Mapped to Error Codes

For a general list of HTTP codes and how they map to error codes generated by the Messaging 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 SMS compliance best practices, please refer to the Messaging Compliance page.

Standard Messaging API