Sending SMS with Delivery Receipts

Overview

The Atmosphere® Messaging API makes it easy to send and receive SMS messages through your IntelePeer DID or Toll-Free phone numbers. Short Codes and Alphanumeric Codes are also available. Send-only for SMS messages through Alphanumeric Codes. In this document, you’ll find instructions on how to configure your numbers to send SMS messages with delivery receipts.

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

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, shortcode, alphanumeric sender id)

e.g., 1-12345, 57-Hello8, +13031112222

See Code Formatting for more information

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
dlr BOOLEAN Optional Set to True enable delivery receipt on this request (default=False)
dlroptions Object Optional May be optionally supplied when “dlr” is set to true to set additional DLR options beyond the standard behavior
dlroptions.include-accepted BOOLEAN Optional

If set to True, the system will generate an additional intermediary DLR which indicates when the MT message is successfully enqueued into the SMS network. This DLR will reflect the state ACCEPTD when received.

This DLR represents a positive-confirmation DLR and not negative-confirmation. As such, if requested, the lack of receipt of this DLR is an indication of failure to enqueue the message to the SMS network.

This is primarily used when final delivery status through the carrier/handset is unavailable in the destination country.

guid STRING Required An identifier to be appended to the message in the Message Detail Record for correlation with other system records.

Request Example for Long Codes

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

Copy
{
"from": "+12191112222",
"to": "+13038675309",
"text": "Hello World!",
"dlr": true,
"guid": "1123123123123123"
}
{
"from": "+13032225555",
"to": "+172034448888",
"text": "Hello World",
"dlr": true,
"dlroptions": {
"include_accepted": true
},
"guid": "1122334455667788"
}

Sending a SMS Message with Delivery Receipts

A Delivery Receipt (DLR) provides you the details of success or failure of your outbound SMS messages. There are three phases at which progress can be confirmed:

  • API Acknowledgment – IntelePeer will send an acknowledgment to the API call to our systems. A 202 message means the message is progressing. More details on response codes can be found here.
  • Checking Message Status – Once the IntelePeer Servers have sent a message downstream, the Message Detail Records (MDR) is updated with a further status. More details can be found here.
  • Optional Delivery Receipt – IntelePeer provides an optional parameter on an outbound message to receive a Delivery Receipt (DLR) from the Mobile Provider to which the message is sent.

Delivery Receipt Message States

Message State Status Description
DELIVERED DELIVRD Message is delivered to destination
EXPIRED EXPIRED Message validity period has expired
DELETED DELETED Message has been deleted
UNDELIVERABLE UNDELIV Message is undeliverable
ACCEPTED ACCEPTD Message is in accepted state (i.e., has been manually read on behalf of the subscriber by customer service)
UNKNOWN UNKNOWN Message is in invalid state
REJECTED REJECTD Message is in a rejected state
  • Delivery Receipt Message States are provided to IntelePeer by mobile carriers and we pass them to our customers unaltered. More information about Delivery Receipts can be found on the SMS Delivery Receipts page.

  • The Message State sent for Carrier DLR and Handset DLR are the same.

Setting Up Your System to Receive DLRs

SMS DLRs are delivered in the same way that an inbound message is delivered – to a customer dedicated webhook.

There are three steps to set up and test delivery receipts, after SMS has been set up on an account and (at least) one number has been SMS provisioned.

The format for DLRs are application/json to and they are sent to your DLR webhook in the following format:

When sending an SMS, the message may be split into multiple segments in transit. If the final carrier supports DLRs, you should expect to receive a DLR webhook POST for each segment. The number of segments your message is split into is returned in the original send request.

Task 1: Set up your webserver to receive DLR webhooks

Just like your inbound SMS webserver, it should support receiving HTTP POST messages on an endpoint with an expected content type of application/json.

Task 2: Configure Your Account’s DLR webhook

Unlike inbound SMS messages, where each code can have a unique webhook for delivery, all DLRs are delivered to the same webhook. To set up this webhook, provide the URL through the existing “account configuration” endpoint, but provide a “dlrwebhook” parameter to your JSON request.

Example DLR

Copy
{
"content": "DLR",
"from": "+18001112222",
"to": "+12223334444",
"refid": "SM5C59B99900012345671000F9170FDB",
"status": "DELIVRD",
"message_state": "DELIVERED"
}

 

Field Name Description
content “Always DLR”
from The sending code
to The receiving SMS-enabled handset
refid The reference identifier for the message, which was passed back in the original send request
status The final status of the message. Values per SMPP Protocol Specification v3.4, Table B-2
message_state Should be present for SMSC Delivery Receipts and Intermediate Notifications. Will be set to null when not available. Values per SMPP Protocol Specification v3.4, 5.2.28

Sample Code (Python 2.7+)

Copy
import requests
url = "https://api.intelepeer.com/_rest/v4/app/sms/accountcfg"
payload = {
"dlrwebhook": "https://www.mycompany.com/sms/dlr"
}
headers = {
"Authorization": "Bearer INSERT_API_TOKEN_HERE",
"Content-Type": "application/json",
"cache-control": "no-cache"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)

This same endpoint is also used to set up your account secret which can be provided in the same request under the parameter, “secret”.

Task 3: Send an SMS message using the API (with DLR enabled in the request)

Task 4: Validate Delivery Receipts are being delivered to your webhook

Upon sending an SMS message, and receiving it on a cellphone, you should expect to see your webhook receive one request per segment which that SMS was split into.