We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More

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

NameDefaultDescriptionExample
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

CodeDescriptionSolutions
200 OKThe request was successful and should contain the requested data. 
207 Multi-StatusThe 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 RequestThe 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 UnauthorizedThe 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 ForbiddenThe 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 TypeThe 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 EntityThe 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 ErrorThe request has not been fulfilled due to a server error.Please report this error and contact support for further assistance.
([email protected])

Response Headers

NameDescriptionExample
Content-TypeAt this time, only application/json is supported and will be returned.
Content-Type: application/json
X-CDR-IDAn 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.

ParameterTypeDescriptionExample
Root
idStringThe ID used to identify the message."my_message_id1"
from *StringThe 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 *StringThe message body that will be sent to the recipient. (Maximum of 2048 characters)"Hello World"
encode_asInteger
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
priorityInteger (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_reportString
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"
"always"
request_mclBoolean

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_inStringString 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_atDatetimeUsed 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_inStringUsed 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_atDatetimeUsed 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

ParameterTypeDescriptionExample
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 *StringAlways "outbound""outbound"
from *StringThe sender number"12003004000"
to *StringThe recipient number, which is identical to the key."12003004001"
type *StringThe created message type which may be an sms or mms message based on content adaption if available."sms"
partsArray<Part>A list of sms messages that make up the complete request.
body *StringThe 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 *StringDenotes under what conditions a delivery report be sent back for the message."always"
remote_service_providerString

The name of the service provider.

This field will not be present if MCL is unavailable.

"ACME Corp."
remote_reference_idString

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"
remote_countryString

Country name of remote_number if available, otherwise it will be an empty string.

"United States"
remote_country_codeString

Two-Character ISO country code of the remote number if available, otherwise it will be an empty string.

"US"
remote_messaging_enabledString

If the remote_number is messaging enabled, may be nil if indeterminate

true
inserted_atDatetimeDenotes the time the system successfully accepted the message."2020-04-18T11:30:00Z"
updated_atDatetimeDenotes when the message's status was last modified."2020-04-18T11:30:00Z"
expires_atDatetimeDenotes the time the meassage expires."2020-04-18T11:30:00Z"
scheduled_atDatetimeThe expected time that the message will actually attempt to be sent to the ecosystem."2020-04-18T11:30:00Z"
sent_atDatetime

Denotes when the message was sent.

Will always be nil upon return from an sms request.

"2020-04-18T11:30:00Z"
delivered_atDatetime

Denotes when the message was delivered.

Will always be nil upon return from an sms request.

"2020-04-18T11:30:00Z"
udhUDHAn object containing the UDH information of the request if it was split into multiple messages.
csp_campaignCSPCampaignAn object containing the Campaign information of the request, if available.
UDH
ref_num *IntegerThe number assigned to the segments that is used identify them for transport.24
count *IntegerThe number of segments that were created for the request.3
Part
id *StringThe ID supplied by the system to identify the segment."01EYVMVWJQ9F3VYAJ833W9GZJ9"
CSPCampaign
idString

The Tychron issued UUID for the campaign.

This will be null if no campaign is available.

"c045cf8c-0d97-4241-9f03-1a80ba1d7acb"
tcr_brand_idStringTCR issued Brand ID."B123456"
tcr_campaign_idStringTCR issued Campaign ID."C123456"

Response Types

TypeDescription
smsAn sms forward request.
sms_dlrAn 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.

EncodingParameter Value
GSM 7bit (unpacked)0
ASCII1
Latin-13
UCS-2 / UTF-168

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.

SuffixDuration TypeDuration Multiplier (in milliseconds)
sSeconds1000
MMinutes6000
HHours3600000
DDays86400000
WWeeks604800000

Examples

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