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)

Copy
{
"from": "1-12345",
"to": "+13038675309",
"text": "Hello World!",
"guid": "1123123123123123"
}

The “from” parameter when sending to Long Codes must be in E.164 format

Copy
{
"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)

Copy
{
"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:

  • The telephone number is not the proper Short Code format
  • The telephone number has not been enabled for SMS
  • To/text fields are not present in the request
401

One of the following errors occurred:

  • Authorization token has expired
  • The user does not own telephone number
  • Enterprise is not currently enabled for SMS API access
403 The international destination is not available
404 The telephone number is not available for use by the customer

Response Example

Copy
{
"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:

  1. Message queued for delivery
  2. Message delivered to the mobile carrier
  3. 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

Copy
[
{
"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

Copy
{
"code": 207,
"responses": [
{
"state": "Queued",
"code": 202,
"refid": "SM5C804F0D000999999910009AD59930",
"numparts": 1
},
{
"state": "Queued",
"code": 202,
"refid": "SM5C804F0D000999999910009AD59930",
"numparts": 1
}
]
}