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.
- Request Requirements
- Send an SMS
- Obtain Transaction Status Results
- Buy a Phone Number (Sender ID)
- Inbound SMS
- URL Shortener
- SMS API Examples
- Compliance
Request Requirements
- Base URL:
https://rest-ww.telesign.com/v1/messaging
- Authentication: Basic (easiest to implement) or Digest
- Encoding: Accepts only UTF-8 unicode characters as inputs.
- MIME Type:
application/x-www-form-urlencoded
- Required Headers:
Content-Type - application/x-www-form-urlencoded
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
There are two ways to check the status of your transactions:
- Get Status API - Get the status of an individual transaction by querying a REST API, for up to 12 hours after sending your message.
- Transaction Callback Service - Receive status updates from TeleSign about multiple transactions, at a URL that you provide. Receive status updates from TeleSign about multiple transactions, at a URL that you provide. We recommend using this when you have a high volume of transactions.
Buy a Phone Number (Sender ID)
TeleSign offers the option of buying a sender ID (dedicated phone number) through us to use to send messages with the SMS API. For more details see Phone Numbers API.
Inbound SMS
If you need to receive messages back from customers, a related service that we offer is Inbound SMS. For more about this service, see Inbound SMS.
Speak with our Customer Support Team 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.
The phone number in the example is for display only.
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&external_id=CustomExternalID_7349&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):
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": "CustomExternalID7349",
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"status": {
"code": 290,
"updated_on": "2017-31-03T14:51:28.709526Z",
"description": "Message in progress"
}
}
GET Request and Response Examples
You use a GET request to retrieve status information about your POST request.
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:
{
"external_id": "CustomExternalID7349",
"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 articles in the Compliance section in our Support Center.
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.