Sending SMS Messages via Short Codes

The Atmosphere® Messaging API makes it simple to send and receive SMS messages through your IntelePeer Short Codes.

All IntelePeer Short Codes can be used to send and receive SMS messages. Alphanumeric shortcodes cannot receive SMS messages.

Sending a single SMS Message

You can send an SMS Short Code message with a single call to the Atmosphere® Messaging API.

Please ensure you are following IntelePeer API conventions.

URI

POST to https://api.intelepeer.com/sms/v4/app/sms/send

Parameters

This API method requires an Authorization Token. Learn more about the Authorization token in Atmosphere® API Authentication.

ParameterData TypeRequired
fromstringrequiredShort Code-formatted number (CountryCode-ShortCode) to which the message is being sent from (e.g., 1-12345, 57-1234)
tostringrequiredE.164-formatted number to which the message is being sent to (e.g., +13038675309)
textstringrequiredThe message to be sent
guidstringoptionalAn identifier to be appended to the message in the Message Detail Record for correlation with other system records.
Short Code Example
{

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

 

Response Codes
Response CodeDescription
202SMS message has been successfully queued for delivery to the destination phone number.
400One 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
401One 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
403The international destination is not available
404The telephone number is not available for use by the customer

 

Response Example
{
    "state": "CREATED",
    "refid": "SM5AC09A610001006568100005C32E9D"
}

 

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 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. 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 single-send API responds with a reference identifier (refid) as well as status information about the request. The bulk-send API returns a list of these responses in the object-key, “responses”, where each response corresponds to the associated request.

The bulk HTTP 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": "SM5BE9B76600099999991000DE162EE8"
    },
    {
      "state": "Queued",
      "code": 202,
      "refid": "SM5BE9B766000999999910008CF7795C"
    }
  ]
}