Receiving SMS DLR via HTTP (Webhooks)

Introduction

SMS DLRs can be delivered to an HTTP endpoint.

Prerequisites

To begin receiving SMS DLRs via HTTP, a few items are required:

HTTP Capable Server
JSON Parser
An SMS capable DID (Direct Inward Dial)
A Switch that is SMS enabled and pointing to the HTTP endpoint

Authorization

You may add authorization to your HTTP endpoint. Available authorization methods include:

None
Basic
Bearer

Supported Output Types

The SMS DLR Webhook only supports JSON as an output type.

Request Format

POST /inbound HTTP/1.1
Host: example.com
Accept: application/json, text/plain
Content-Type: application/json; charset=utf-8
X-Message-ID: 01FYVT3Y75441CNCCT3TJVWVF3
X-Message-Format: trinity_json_1_0

{
  "id": "01FYVT3Y75441CNCCT3TJVWVF3",
  "type": "sms_dlr",
  "from": "12003004000",
  "to": "12003004001",
  "status": "processing",
  "error_code": "ok",
  "delivery_status": "delivered",
  "delivery_error_code": "000",
  "inserted_at": "2022-05-06T16:10:22.665143Z",
  "updated_at": "2022-05-06T16:10:22.665143Z",
  "done_at": "2022-05-06T16:10:22.665143Z",
  "submitted_at": "2022-05-06T16:10:22.665143Z",
  "sms": {
    "id": "01E7NBVFJA6GQTEEV0YAQP9EMT"
  }
}

Request Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Description	Example
Root
id *	String	The ID used to identify the DLR.	"01E7NBVFJA6GQTEEV0YAQP9EMT"
type *	String	Paramter used to specify whether the message is a SMS message or SMS Delivery Receipt.	"sms_dlr"
from *	String	The sending number that will appear in the message. The number must be formatted in a plain format, e.g (12003004000).	"12003004000"
to *	String	The recipient number of the message. The number must be formatted in a plain format, e.g (12003004000)	"12003004001"
status *	String	Last known processing status of the DLR message being delivered. This can be safely ignored for most usecases.	"processing"
error_code *	String	Last error code set on the DLR during processing.	"ok"
delivery_status *	String	The delivery report status received from carriers.	"delivered"
delivery_error_code *	String	The plain delivery error code normally 3 alphanumeric characters.	"000"
inserted_at *	Datetime	An ISO 8601 formatted timestamp that represents when the message was received by the API.	"2020-05-06T16:10:22.665143Z"
updated_at *	Datetime	An ISO 8601 formatted timestamp that represents when the message was last updated by the API.	"2020-05-06T16:10:22.665143Z"
done_at	Datetime	An ISO 8601 formatted timestamp that represents when the message was considered delivered.	"2020-05-06T16:10:22.665143Z"
submitted_at	Datetime	An ISO 8601 formatted timestamp that represents when the message was registered as submitted to the carrier.	"2020-05-06T17:00:00.000000Z"
sms	SMS	An object containing limited information on the SMS that the DLR belongs to
SMS
id	String	The id of the SMS message part associated with the DLR.	01E7NBVFJA6GQTEEV0YAQP9EMT

Response Format

Acknowledge / No-Reply

Returning a 204 status acknowledges the

HTTP/1.1 204 No Content

References

Plain Format

The plain format contains only the digits of the phone number with no additional prefixes. It is almost identical to the E.164 format but without the prefix.

Examples: 12003004000, 332828373552

Delivery Status

delivered
expired
deleted
undelivered
accepted
unknown
rejected
failed
enroute
skipped