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.

 

ParameterData TypeRequiredContent

from

 

 

 

 

 

 

 

 

stringrequired

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

 

to

 

 

 

 

stringrequired

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

 

text

 

stringrequired

The message to be sent

 

dlr

 

 

 

booleanoptional

Set to true enable delivery receipt on this request (default=false)

 

guidstringoptional

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.

 

{

"from": "+12191112222",

"to": "+13038675309",

"text": "Hello World!",

"dlr": true,

"guid": "1123123123123123"

}

Sending an 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 Acknowledgement – IntelePeer will send an acknowledgment to the API call to our systems. A 202 message means the message is progressing and more details on response codes can be found at: https://www.intelepeer.com/products/documentation/sms/api/send-sms-messages/
  •  Checking Message Status – Once the IntelePeer Servers have sent a message downstream the Message Detail Records [MDR] is updated with a further status which can be found at https://www.intelepeer.com/products/documentation/sms/api/check-message-status/
  • Optional Carrier Acknowledgement / Confirmation – 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 and more details can be found on this page.

 

Delivery Receipt Types

 

  • Carrier Acknowledgment: The outbound message has reached the carrier SMSC successfully and it is being processed for delivery to the end-user for A2P. For mobile providers in many countries confirmation that the message has reached the SMSC is all that is available.
  • Carrier Confirmation – The carrier has sent the outbound message to the end-user’s mobile device.

 

The Message State sent for Carrier Acknowledgement and Carrier Confirmation are the same. Your IntelePeer Solutions Engineer can tell you what is available for specific providers in a country.

 

Delivery Receipt Message States

 

Message StateStatusDescription

DELIVERED

 

 

DELIVRDMessage is delivered to
destination

EXPIRED

 

 

EXPIREDMessage validity period has
expired.

DELETED

 

DELETEDMessage has been deleted

UNDELIVERABLE

 

UNDELIVMessage is undeliverable

ACCPTED

 

 

 

 

 

ACCEPTDMessage is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service)

UNKNOWN

 

UNKNOWNMessage is in invalid state
REJECTEDREJECTDMessage is in a rejected state

 

Delivery Receipt Message States are provided to IntelePeer by mobile carriers and we pass them to our customers unaltered. There are a few items to consider when looking at a DLR:

 

  • Not all carriers return DLRs
  • Some carriers who do return DLRs may not always do so reliably. Carriers across the globe have been known to change this offering without notice, therefore the lack of a DLR may not indicate an issue with the system.
  • As noted above, in some cases a DLR represents the delivery of a message to the SMSC [Carrier Acknowledgement] and in others the delivery of a message to the Handset [Carrier Confirmation].
  • Carriers will send the DLR back prior to applying SPAM filters. This is done to prevent spammers from trying to circumvent the Carriers SPAM Filter algorithms.
  • Intermediate message status is not currently available.

 

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

{

"content": "DLR",

"from": "+18001112222",

"to": "+12223334444",

"refid": "SM5C59B99900012345671000F9170FDB",

"status": "DELIVRD",

"message_state": "DELIVERED"

}

Field NameDescription

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_stateShould 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+):

 

import requests



url = "https://api.intelepeer.com/sms/v4/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.