logo
API Reference
Tutorials
SDKs
Legacy
Legal & Compliance
Support
No results found.
Authentication
Try the API Explorer
Get Started
Transaction Callback Service
Inbound SMS
URL Shortener
Codes, Languages, and Time Zones
Understand TeleSign Status and Error Codes
All Status and Error Codes
Want to provide feedback?

Write to docs@telesign.com.

Get Started with the SMS API

TeleSign’s SMS 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).

This page provides instructions and references for features of the SMS API and associated tools.

General Information

All requests submitted for the SMS API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-ww.telesign.com/v1/messaging as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type application/x-www-form-urlencoded in request headers

Send an SMS

For quick instructions about how to send your first SMS, see the Send an SMS page.

For a list of available parameters, see the POST v1/messaging page.

Obtain Transaction Status Results

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

  • Status Request - quickly get the status of a transaction with a GET request.
  • Transaction Callback - TeleSign uses a POST request to post status information about your transactions to a URL that you provide. (Recommended for high volume transactions.)

Read more about these options on the Obtain Transaction Status Results page.

Buy a Phone Number (Sender ID)

TeleSign offers the option of buying a sender ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number.

You can use the Phone Numbers API to buy a phone number. This is best if you do not need to buy numbers in areas that have special restrictions. Details about the Phone Numbers API (and what areas have restrictions) are available on the Get Started with the Phone Numbers API page.

Alternatively, you can speak with your Customer Success Manager to purchase one or more phone numbers to use as a sender ID. You need at least one if you want to receive messages using inbound SMS.

Inbound SMS

If you need to receive messages back from customers, an optional feature that can be made available is inbound SMS. You can learn more about this feature by reviewing the Inbound SMS page.

If you want to enable this feature, you must have:

  • a phone number available for use as a sender ID
  • a callback URL
NOTE:

Speak with your Customer Success Manager to enable this feature.

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.

SMS API Examples

This section provides examples of a request and response using the SMS API.

POST Request and Response Examples

You use a POST request to send your message.

NOTE:

The phone number in the example is for display only.

Example POST Request with the SMS API
POST https://rest-ww.telesign.com/v1/messaging HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT

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

Here is an example POST response (when you use transaction callbacks to retrieve status information):

Example POST Response
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

{
   "external_id": "Custom external ID",
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "status": {
      "code": 290,
      "updated_on": "2017-31-03T14:51:28.709526Z",
      "description": "Message in progress"
   },
   "additional_info": {
      "code_entered": null,
      "message_parts_count" : 1
   }
}

GET Request and Response Examples

You use a GET request to retrieve status information about your POST request.

Example GET Request with the SMS API 
GET https://rest-ww.telesign.com/v1/messaging/ABCDEF0123456789ABCDEF0123456789 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:53:11 GMT

The GET response body looks like this:

Example GET Response
{
  "external_id": "Custom external ID",
  "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"
  },
  "additional_info": {
    "mnc": "03",
    "mcc": "220"
  }
}

Compliance

For SMS compliance best practices, please refer to the SMS Compliance section of the Compliance page.

Next Steps

This section offers some suggestions for next steps to take.

  • Send an SMS - Use TeleSign’s SMS API Explorer to send your first request.
  • POST v1/messaging - View the API reference page for sending an SMS request.