Sending SMS Messages
The Atmosphere® Messaging API makes it simple to send and receive SMS messages through your IntelePeer Short Codes and Long Codes.
All IntelePeer Short Codes and Long Codes can be used to send and receive SMS messages. Alphanumeric sender IDs cannot receive SMS messages.
Sending a Single SMS Message
You can send an SMS message with a single call to the Atmosphere® Messaging API.
Please ensure you are following IntelePeer API conventions.
URI
For EU numbers, POST to https://eu.api.intelepeer.com/_rest/v4/app/sms/send
For all other numbers, POST to https://api.intelepeer.com/_rest/v4/app/sms/send
Parameters
This API method requires an Authorization Token. Learn more about the Authorization token in Atmosphere® API Authentication.
Parameter | Data Type | Required? | Description |
---|---|---|---|
from | STRING | Required |
Properly formatted customer inventory code (long code, short code, alphanumeric sender id) e.g., 1-12345, 57-Hello8, +13031112222) See Code Formatting for more informaiton |
to | STRING | Required | E.164-formatted number to which the message is being sent to (e.g., +13038675309) |
text | STRING | Required | The message to be sent |
guid | STRING | Optional | An identifier to be appended to the message in the Message Detail Record for correlation with other system records |
Request Examples
The “from” parameter when sending to Long Codes must be in the Short Code-formatted number format (CountryCode-ShortCode)
{
"from": "1-12345",
"to": "+13038675309",
"text": "Hello World!",
"guid": "1123123123123123"
}
The “from” parameter when sending to Long Codes must be in E.164 format
{
"from": "+12191112222",
"to": "+13038675309",
"text": "Hello World!",
"guid": "1123123123123123"
}
The “from” parameter when sending to non-US Long Codes must be in the Short Code-formatted number format (CountryCode-Alphanumeric)
{
"from": "57-MyCompany",
"to": "+573132341111",
"text": "Hello World!",
"guid": "1123123123123123"
}
Response Codes
Response Code | Description |
---|---|
202 | SMS message has been successfully queued for delivery to the destination phone number. |
400 |
One of the following errors occurred:
|
401 |
One of the following errors occurred:
|
403 | The international destination is not available |
404 | The telephone number is not available for use by the customer |
Response Example
{
"state": "Queued",
"code": 202,
"refid": "SM5C804F0D000999999910009AD59930",
"numparts": 1
}
Behavior
Messages sent through the Atmosphere® Messaging API are queued for quick and reliable delivery to the destination carrier and ultimately to the end-user’s phone.
You can check the status of a message at any time after sending it. Learn more about Checking Message Status.
The message’s lifecycle is as follows:
- Message queued for delivery
- Message delivered to the mobile carrier
- Message delivered to the desired recipient
There may be delays in delivery of a message to the end-customer due to:
- Throttling enforced by IntelePeer to improve message delivery
- The end customers handset being out of service area, turned off, or in airplane mode
There may be message delivery failures due to carrier SPAM filters or the carrier-specific restrictions.
Sending SMS Messages in Bulk
The same API above can also be used to send messages in bulk. The following describes the differences between the single-API and the bulk-API:
Changes to the Request for Bulk API
The single-send API requires a single object which contains the message parameters. The same API can be used to create a bulk send request by passing a list of requests in the request body. To use the bulk-send API, simply turn your JSON into a list of these objects:
Example
[
{
"from": "1-12345",
"to": "+13038675309",
"text": "Hello World test 1",
"guid": "1123123123123123"
},
{
"from": "1-98765",
"to": "+13038678888",
"text": "Hello World test 2",
"guid": "myguid1"
}
]
Changes to the Response for Bulk API
The send API responds with a reference identifier (refid) as well as status information about the request.
Corresponding with the change of the request to a list, the API returns a list of responses in the object-key, “responses”, where each response corresponds to the associated request.
When utilizing the bulk request format of the API, the response code will generally be 207 regardless of the status of individual messages unless an error occurs at the overall request level.
Example
{
"code": 207,
"responses": [
{
"state": "Queued",
"code": 202,
"refid": "SM5C804F0D000999999910009AD59930",
"numparts": 1
},
{
"state": "Queued",
"code": 202,
"refid": "SM5C804F0D000999999910009AD59930",
"numparts": 1
}
]
}