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 SMS Request 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.

Speak with your TAM to purchase one or more phone numbers to use as 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 Technical Account 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.

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

Here is an example POST response:

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

{
   "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 looks like this:

Example GET Response
{
  "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