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

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.

For more details about buying a phone number, refer to the Buy a Phone Number (Sender/Caller ID) page.

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

URL Shortener

TeleSign no longer offers a URL shortener with Standard products.

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-api.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=15555551234&message=Your message here.&account_lifecycle_event=create&originating_ip=203.0.113.45

Here is an example POST response body to a callback:

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-api.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:

{
  "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.