Get Started

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.

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
{
   "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-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 page in our Support Center.


Next Steps

This section offers some suggestions for next steps to take.

Did this page help you?