Receiving SMS via HTTP (Webhooks)

Introduction

SMS messages can be delivered to an HTTP endpoint.

Prerequisites

To begin receiving SMS messages 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 API 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
X-Message-ID: 01E7NBVFJA6GQTEEV0YAQP9EMT
X-Message-Format: trinity_json_1_0

{
  "id": "01E7NBVFJA6GQTEEV0YAQP9EMT",
  "type": "sms",
  "from": "12003004000",
  "to": "12003004001",
  "csp_campaign": {
    "id": "74341b5b-fb66-4570-b318-d4ba587318e9",
    "tcr_brand_id": "B123456",
    "tcr_campaign_id": "C123456"
  },
  "remote_service_provider": "ACME Corp",
  "remote_reference_id": "us_acme",
  "parts": [
    {
      "id": "01E7NBW1PZTNVBZEQMMQ3ZARDS"
    },
    {
      "id": "01E7NBWNBDTPWTD99QEYJ0VPH6"
    }
  ],
  "body": "Hello World",
  "sms_encoding": 3,
  "priority": 1,
  "request_delivery_report": "Always",
  "udh": {
    "ref_num": 1,
    "count": 4
  },
  "inserted_at": "2022-05-06T16:10:22.665143Z",
  "updated_at": "2022-05-06T16:10:22.665143Z",
  "processed_at": "2022-05-06T16:10:22.665143Z",
  "delivered_at": "2022-05-06T16:10:22.665143Z",
  "scheduled_at": "2022-05-06T17:00:00.000000Z",
  "expires_at": "2022-05-06T20:00:00.000000Z"
}

Request Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Description	Example
Root
id *	String	The ID used to identify the message.	"01E7NBVFJA6GQTEEV0YAQP9EMT"
type *	String	Paramter used to specify whether the message is a SMS message or SMS Delivery Receipt.	"sms"
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"
body *	String	The body of the message that was received, the body will always be encoded in UTF-8, it is not necessary to decode using the sms_encoding.	"Hello World"
priority *	Integer (0..2)	The original priority of the message	1
sms_encoding *	Integer	The original encoding of the message, this field is only provided for reference and should not be acted upon to decode the body.	3
request_delivery_report	String	Used to specify if a delivery receipt is required and when it should be sent based on the request. This parameter can be specified as either "no", "always", "on_success", and "on_error".	"no"
remote_service_provider	String	The carrier or service provider of the remote_number.	"ACME Corp."
remote_reference_id	String	A Tychron issued ID for grouping service providers for billing purposes.	"us_acme"
udh	UDH	A map containing the user data header (UDH) information of a message.
parts	Array<Part>	An array containing the ids for each part in a multipart message. This parameter may be empty if the message is not a multipart message.
csp_campaign	CSPCampaign	A map containing basic information on the Campaign associated with this message.
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"
processed_at *	Datetime	An ISO 8601 formatted timestamp that represents when the message was processed by the API.	"2020-05-06T16:10:22.665143Z"
delivered_at	Datetime	An ISO 8601 formatted timestamp that represents when the message was considered delivered. Delivery confirmation requires a delivery report/receipt.	"2020-05-06T16:10:22.665143Z"
scheduled_at	Datetime	An ISO 8601 formatted timestamp that represents when the message was scheduled for delivery.	"2020-05-06T17:00:00.000000Z"
expires_at	Datetime	An ISO 8601 formatted timestamp that represents when the message will be considered expired.	"2020-05-06T20:00:00.000000Z"
Part
id *	String	The ID of a single SMS segment.
UDH
ref_num *	Integer	An ID representing the entire message's reference number in Tychron's network.	253
count *	Integer	Denotes how many parts the entire message consists of.	3
CSPCampaign
id	String	The Tychron issued UUID for the campaign.	"c045cf8c-0d97-4241-9f03-1a80ba1d7acb"
tcr_brand_id	String	TCR issued Brand ID.	"B123456"
tcr_campaign_id	String	TCR issued Campaign ID.	"C123456"

Response Format

JSON Reply

Responding to a request with a JSON document will "reply" to the request, that is, it will send a message back to the sender based on the body returned.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "sms",
  "body": "Hello, World"
}

Text Reply

Responding to a request with a text document will "reply" to the request, that is, it will send a message back to the sender based on the body returned.

HTTP/1.1 200 OK
Content-Type: text/plain

This is a response!

Acknowledge / No-Reply

To avoid replying to a message, a 204 status can be returned instead.

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