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.

 

ParameterData TypeRequired
fromstringrequired

Properly formatted customer inventory code (long code, shortcode, alphanumeric sender id)
 
(e.g., 1-12345, 57-Hello8, +13031112222)
see: Code Formatting

 

to

 

 

 

 

 

stringrequiredE.164-formatted number to which the message is being sent to (e.g., +13038675309)

text

 

stringrequiredThe message to be sent
guidstringoptionalAn identifier to be appended to the message in the Message Detail Record for correlation with other system records.

 
Request Examples

The “to” parameter for sending from Long Codes must be in the Short Code-formatted number format (CountryCode-ShortCode)

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

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

{
    "from": "+12191112222",
    "to": "+13038675309",
    "text": "Hello World!",
    "guid": "1123123123123123"
}

The “to” parameter for sending from Alphanumeric Sender IDs 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:
 

  • 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

{
    "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. 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. The same API can be used to create a bulk send request by passing a list of requests in the request body.

 

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
    }
  ]
}