Sending SMS DLR via HTTP
Introduction
The SMS-DLR API is an HTTP endpoint used to send SMS DLR messages.
Endpoint
POST /sms HTTP/1.1
Host: sms.tychron.onlineRequest Headers
| Name | Default | Description | Example |
|---|---|---|---|
| Accept | application/json | Only JSON is currently supported for sending SMS via HTTP. | |
| Authorization | Bearer KEY | Please use your API Key's HTTP Token for authorization. | |
| Content-Type | This header denotes the data type of a request body. | |
Response Codes
| Code | Description | Solutions |
|---|---|---|
| 200 OK | The request was successful and should contain the requested data. | |
| 207 Multi-Status | The request was understood and well formed, but one or more recipients have failed. This status may also be used if a recipient is not allowed (e.g. international, shortcode or sender-id) | The 207 request body will be similar to the 200 status, however one or more recipients will have an error status. |
| 400 Bad Request | The payload body of the request is malformed or the request contains invalid parameters. | Check your JSON payload for invalid or missing parameters, or run it through a JSON linter. |
| 401 Unauthorized | The request may be deemed unauthorized due to a number of factors.
| This error typically results from using an incorrect API token in requests. Check your API token for typos. If the error persists, please contact support. ([email protected]) |
| 403 Forbidden | The user is not permitted to make the specified request(s). In this instance, the user is likely not authorized to use the SMS API. | This error typically results from using an incorrect API token in requests. Check your API token for typos. Please contact support for additional details.([email protected]) |
| 415 Unsupported Media Type | The content-type used to make the request is not supported. At this time, only JSON is supported. | Convert the request to JSON.Content-Type: application/json |
| 422 Unprocessable Entity | The parameters of the request body failed validation or contain invalid values. | The response body will contain specific details for the request failure. Correct the request parameters based on these details. |
| 500 Internal Server Error | The request has not been fulfilled due to a server error. | Please report this error and contact support for further assistance. ([email protected]) |
Response Headers
| Name | Description | Example |
|---|---|---|
| Content-Type | At this time, only application/json is supported and will be returned. | |
| X-CDR-ID | An ID used to identify the CDR (Call Detail Record) generated by the request. Please provide this ID for any billing questions when contacting support. | |
Supported Output Types
The SMS API only supports JSON as an output type.
Request Format
POST /sms HTTP/1.1
Accept: application/json
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json{
"id": "message1id",
"type": "sms_dlr",
"from":"+12003004000",
"delivery_status": "delivered",
"delivery_error_code": "000",
"sms_id": "01GTFCEBFR5RJG3RWXCD8QRDZN"
}Request Parameters
Fields marked with a * are mandatory.
| Parameter | Type | Description | Example |
|---|---|---|---|
| Root | |||
| id | String | The ID used to identify the message. | "my_message_id1" |
| type * | String | Must be set to "sms_dlr". | "sms_dlr" |
| from * | String | The sending number that will appear in the DLR. The number must be formatted in E164 format, e.g. (+12003004000). | "+12003004001" |
| delivery_status | String |
| "delivered" |
| delivery_error_code | String | Normally a three digit code further describing an error, contact support for a full detailed list of error codes. | "000" |
| sms_id * | String | The ID of the SMS message this delivery report is being created for, note that is REQUIRED. .Please note for multipart messages, each segment will require its own DLR. | "01EYVMVWJQ9F3VYAJ833W9GZJ9" |
| request_mcl | Boolean | When sending to a valid TenDLC number the basic MCL data can be returned in the immediate request. Your account may not allow MCL on SMS requests, if you would like to have MCL return on request, or regardless of this flag being set, please contact support. Note that MCL charges may apply if this flag is set to true (unless explictly disabled by your account). | false |
Response Format
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: uYmqci22QoeTA8Zj{
"01GTFCEBFR5RJG3RWXCD8QRDZN": {
"id": "01GTFCJRXEBPXERXET9J06FS05",
"direction": "outbound",
"from": "12003004000",
"to": "12003004001",
"type": "sms_dlr",
"body": "id:01GTFCEBFR5RJG3RWXCD8QRDZN sub:000 dlvrd:000 submit date:2303012007 done date:2303012008 stat:DELIVRD err:000 text:",
"encoding": 0,
"inserted_at": "2021-02-18T22:39:43Z",
"updated_at": "2021-02-18T22:39:43Z",
"processed_at": "2021-02-18T22:39:43Z",
"expires_at": null,
"submitted_at": null,
"done_at": null
}
}Please note the above example is for demonstrative purposes only.
Response Parameters
Parameters marked with * are always present in all requests
| Parameter | Type | Description | Example |
|---|---|---|---|
| Root | |||
| * | Map<String, Response> | A map with the SMS ID as the key and the message response as the value. | |
| Response | |||
| id * | String | The ID supplied by the system to identify the message. Note in the case of multipart (i.e. UDH) messages, this ID will be the "multipart_id" that identifies all segments of the message. | "01EYVMVWJQ9F3VYAJ833W9GZJ9" |
| direction * | String | Always "outbound" | "outbound" |
| from * | String | The sender number | "12003004000" |
| to * | String | The recipient number, extracted from the original SMS. | "12003004001" |
| type * | String | Will always be "sms_dlr" for DLR requests. | "sms_dlr" |
| body * | String | The raw generated DLR body, can be safely ignored, but can also be used for debugging. | "" |
| encoding * | Integer | The encoding that was used for the message. Note that messages will always return in UTF-8, the encoding is provided for informational purposes when diagnosing issues with upstream message delivery. | 3 |
| remote_service_provider | String | The name of the service provider. This field will not be present if MCL is unavailable. | "ACME Corp." |
| remote_reference_id | String | A Tychron issued ID which identifies the carrier the message is destined for, note that is field is only available if "return_mcl" or MCL for SMS Requests is enabled. This field will not be present if MCL is unavailable | "us_acme" |
| delivery_status | String | Will be the same as the requested "delivery_status" | "delivered" |
| delivery_error_code | String | Will be the same as the requested "delivery_error_code" | "000" |
| inserted_at | Datetime | Denotes the time the system successfully accepted the message. | "2020-04-18T11:30:00Z" |
| updated_at | Datetime | Denotes when the message's status was last modified. | "2020-04-18T11:30:00Z" |
| expires_at | Datetime | Denotes the time the meassage expires. | "2020-04-18T11:30:00Z" |
| sent_at | Datetime | Denotes when the message was sent. Will always be nil upon return from an sms request. | "2020-04-18T11:30:00Z" |
| submitted_at | Datetime | Denotes when the original SMS was considered accepted. Will be the current timestamp. | "2020-04-18T11:30:00Z" |
| done_at | Datetime | Denotes when the original DLR was considered accepted. Will be the current timestamp. | "2020-04-18T11:30:00Z" |
| csp_campaign | CSPCampaign | An object containing the Campaign information of the request, if available. | |
| CSPCampaign | |||
| id | String | The Tychron issued UUID for the campaign. This will be null if no campaign is available. | "c045cf8c-0d97-4241-9f03-1a80ba1d7acb" |
| tcr_brand_id | String | TCR issued Brand ID. | "B123456" |
| tcr_campaign_id | String | TCR issued Campaign ID. | "C123456" |
Response Types
| Type | Description |
|---|---|
| sms | An sms forward request. |
| sms_dlr | An sms delivery receipt |
UDH
UDH is one of the methods to create concatenated messages for sending through the sms ecosystem.
Delivered At
It is normal for "delivered_at" and"processed_at" to be null upon request.
References
E.164
E.164 format is the international telephone numbering plan that gives each device on the Public Switched Telephone Network (PSTN) a globally unique number.
The E.164 format consists of a 7 to 15 digit number prepended with a "+" character.
Examples: +12003004000, +332828373552
Encodings
The table below contains all of the encodings supported by Tychron's SMS API. Every payload sent to the API must be made in JSON and encoded in UTF-8.
All SMS messages sent through the API are automatically encoded, but particular encodings may be enforced through the "encode_as" parameter.
To enforce a specific encoding, please reference the table below as needed.
| Encoding | Parameter Value |
|---|---|
| GSM 7bit (unpacked) | 0 |
| ASCII | 1 |
| Latin-1 | 3 |
| UCS-2 / UTF-16 | 8 |