API documentation

Sending SMS via HTTP

Introduction

The SMS API is an HTTP endpoint used to send SMS messages.

Authorization

Please use your API Key's HTTP Token for authorization.

Endpoint

POST /sms HTTP/1.1
Host: sms.tychron.online

Request Headers

Name	Default	Description	Example
Accept	application/json	Only JSON is currently supported for sending SMS via HTTP.	`Accept: application/json,/`
Authorization	Bearer KEY	Please use your API Key's HTTP Token for authorization.	`Authorization: Bearer Rb2VRMSsm0VxHOIcniw6hCJhUqRExQk2`
Content-Type		This header denotes the data type of a request body.	`Content-Type: application/json`

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. The Authorization header is not set. The provided API HTTP token is invalid, expired, or not active. The requesting account may be unauthorized from making requests.	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.	`Content-Type: application/json`
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.	`X-CDR-ID: 01EYVQ227DEWG8YX7FGC0NJ3BC`

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",
  "body": "Hello, World",
  "from":"+12003004000",
  "to": ["+12003004001"],
  "priority": 1,
  "encode_as": 3,
  "request_delivery_report": "always",
  "scheduled_in": "2M",
  "scheduled_at": "2020-04-18T11:30:00Z",
  "expires_in": "3H",
  "expires_at": "2020-04-18T11:30:00Z",
  "request_mcl": true
}

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"
from *	String	The sending number that will appear in the message. The number must be formatted in E164 format, e.g. (+12003004000).	"+12003004001"
to *	Array<String>	The list of recipient number(s). Number(s) must be formatted in E164 format, e.g. (+12003004000). A maximum of 500 numbers can be specified per request.	["+12003004000"]
body *	String	The message body that will be sent to the recipient. (Maximum of 2048 characters)	"Hello World"
encode_as	Integer	Used to encode messages as specified in the request. All messages are automatically encoded if this parameter is not provided. Please see the table below for the list of available encodings.	0
priority	Integer (0..2)	Priority affects the urgency of a message during rate limiting. The higher the priority, the more urgent a message will be. Priorities range from 0 to 2: 0 Low 1 Normal (default) 2 High	1
request_delivery_report	String	Used to specify if a delivery report 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". There is no callback URL in this request: reports are POSTed to the HTTP endpoint configured on the sending number's SMS-enabled Switch — see Receiving SMS-DLR via HTTP and the Switches chapter.	"always"
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
scheduled_in	String	String Used to specify a duration of time that the message will be sent after the request is made. See the table on Duration Strings below for proper formatting.	"12H 30M 10s 1000"
scheduled_at	Datetime	Used to specify the exact date and time the message should be delivered. The timestamp should be formatted using the ISO 8601 standard with a UTC timezone.	"2020-04-18T11:30:00Z"
expires_in	String	Used to specify a duration of time that the message will be deemed expired after the request is made. See the table on Duration Strings below for proper formatting.	"12H 30M 10s 1000"
expires_at	Datetime	Used to specify the exact date and time the message will be deemed expired. The timestamp should be formatted using the ISO 8601 standard with a UTC timezone.	"2020-04-18T11:30:00Z"

Scheduling

The parameter "scheduled_in" takes priority over"scheduled_at". If both parameters are set,"scheduled_in" will overwrite the value set in"scheduled_at". Any parameter that is filled (non-null) is considered set.

Expiration

The parameter "expires_in" takes priority over"expires_at";. If both parameters are set,"expires_in"; will overwrite the value set in"expires_at";. Any parameter that is filled (non-null) is considered set.

Response Format

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: uYmqci22QoeTA8Zj

{
  "12003004001": {
    "id": "01EYVMW463NZSY6E26NMNN7H2N",
    "direction": "outbound",
    "from": "12003004000",
    "to": "12003004001",
    "type": "sms",
    "priority": 1,
    "parts": [
      {
        "id": "01EYVMVWJQ9F3VYAJ833W9GZJ9"
      },
      {
        "id": "01EYVMWDE5ZW9X85D8QX9F3MHN"
      }
    ],
    "body": "Hello, World",
    "encoding": 0,
    "request_delivery_report": "always",
    "udh": {
      "ref_num": 34,
      "count": 2
    },
    "inserted_at": "2021-02-18T22:39:43Z",
    "updated_at": "2021-02-18T22:39:43Z",
    "processed_at": "2021-02-18T22:39:43Z",
    "delivered_at": "2021-02-18T22:39:43Z",
    "scheduled_at": "2021-02-19T00:00:00Z",
    "expires_at": "2021-02-19T06:00:00Z",
    "remote_service_provider": "ACME Corp.",
    "remote_reference_id": "us_acme",
    "remote_country": "United States",
    "remote_country_code": "US",
    "remote_messaging_enabled": true,
    "csp_campaign": {
      "id": "9558525b-694a-4858-bf4d-45502c71041d",
      "tcr_brand_id": "B123456",
      "tcr_campaign_id": "B123456"
    }
  }
}

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 recipient number 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, which is identical to the key.	"12003004001"
type *	String	The created message type which may be an sms or mms message based on content adaption if available.	"sms"
parts	Array<Part>	A list of sms messages that make up the complete request.
body *	String	The body of the message in its complete form, which will be the same as that made in the request, unless a specific encoding was requested.	"Hello, World"
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
priority *	Integer (0..2)	Priority affects the urgency of a message during rate limiting. The higher the priority, the more urgent a message will be. Priorities range from 0 to 2: 0 Low 1 Normal (default) 2 High	1
request_delivery_report *	String	Denotes under what conditions a delivery report be sent back for the message.	"always"
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 this field is only available if "request_mcl" or MCL for SMS Requests is enabled. This field will not be present if MCL is unavailable	"us_acme"
remote_country	String	Country name of remote_number if available, otherwise it will be an empty string.	"United States"
remote_country_code	String	Two-Character ISO country code of the remote number if available, otherwise it will be an empty string.	"US"
remote_messaging_enabled	String	If the remote_number is messaging enabled, may be nil if indeterminate	true
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"
scheduled_at	Datetime	The expected time that the message will actually attempt to be sent to the ecosystem.	"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"
delivered_at	Datetime	Denotes when the message was delivered. Will always be nil upon return from an sms request.	"2020-04-18T11:30:00Z"
udh	UDH	An object containing the UDH information of the request if it was split into multiple messages.
csp_campaign	CSPCampaign	An object containing the Campaign information of the request, if available.
UDH
ref_num *	Integer	The number assigned to the segments that is used identify them for transport.	24
count *	Integer	The number of segments that were created for the request.	3
Part
id *	String	The ID supplied by the system to identify the segment.	"01EYVMVWJQ9F3VYAJ833W9GZJ9"
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

Duration strings

Duration strings are a set of space-separated numbers that are suffixed with a character to denote a period of time.

For example, "10H" represents 10 hours,"10M" represents 10 minutes, and "10s"represents 10 seconds.

Strings that do not contain a suffix are read in milliseconds. For example, "100" is treated as 100 milliseconds.

Please reference the table below as needed.

Suffix	Duration Type	Duration Multiplier (in milliseconds)
s	Seconds	1000
M	Minutes	60000
H	Hours	3600000
D	Days	86400000
W	Weeks	604800000

Examples

10s
30M
2H
6D
3W
0M 6H 5D 2W