Send an SMS Message
On this page
POST /messages: send an SMS to one or more E.164 recipients with optional encoding, scheduling, expiry and delivery-receipt flags.
Overview
This method allows you to send an SMS message. Using TSG Global APIs, you can send outgoing SMS messages from your enabled phone numbers to mobile phones around the globe.
Authentication
Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer <api_key>" (using the messaging API key specifically). API credentials can be found here: https://customer-portal.tsgglobal.com/account
Method
Send an SMS message.
POST https://sms.tsgglobal.world/messages
Sends a new SMS message.
Request Body
| Name | Type | Description |
|---|---|---|
| from* | string | Alphanumeric string representing the sender. Either an E.164 format number or Sender ID. |
| to* | array(string) | One or more recipient numbers in E.164 format. Recipients will be de-duplicated (the same number will only be sent once). |
| body* | string | Message contents. UTF8-encoded. If a custom encoding is specified, this should be a base64 encoded representation of the raw data. |
| encoding | int | Specifies message encoding. |
| force_encoding | int | Normally the system will try to infer what encoding type is best suited for your message, however you can override it using this field instead |
| registered_delivery | int | Defaults to off. Set to request a delivery receipt from the carrier. 1-3 (always, on success, on error) |
| deliver_at | datetime | Specifies a future datetime at which to schedule message delivery. Has to be UTC, e.g. "2017-08-04T08:00:00" |
| expires_at | datetime | Specifies a future datetime when the message should be expired |
The response is a JSON object keyed by recipient number. Each value is a Message object (see Receive an SMS Message for the field reference).
200: single message
A single-segment message sent to 9999999 and 12342341234.
{
"9999999": {
"updated_at": "2017-09-28T08:28:39.132046",
"type": "outbound",
"to": "9999999",
"status": "new",
"scheduled_at": null,
"expires_at": null,
"processed_at": null,
"object": "sms",
"location": null,
"inserted_at": "2017-09-28T08:28:39.132037",
"id": "1e7bd5e9-d9ba-41de-814e-3fe755e60e83",
"from": "15550555055",
"encoding": 3,
"delivery_receipt": 0,
"delivered_at": null,
"body": "hello world"
},
"12342341234": {
"updated_at": "2017-09-28T08:28:39.132046",
"type": "outbound",
"to": "12342341234",
"status": "new",
"scheduled_at": null,
"expires_at": null,
"processed_at": null,
"object": "sms",
"location": null,
"inserted_at": "2017-09-28T08:28:39.132038",
"id": "2e6ed7eb-a16f-4e56-b9f2-f66000921da3",
"from": "15550555055",
"encoding": 3,
"delivery_receipt": 0,
"delivered_at": null,
"body": "hello world"
}
}
200: multipart message
A 3-part multipart message sent to 9999999 and 12342341234. The top-level id always equals the first part's id.
{
"9999999": {
"updated_at": "2017-09-28T08:28:39.132046",
"udh": {
"ref_num": 234,
"count": 3
},
"parts": [
{"id": "3203283d-7a98-49ad-a8d4-17b45a8373b8"},
{"id": "2a87beb4-791c-480d-9b77-1780d785847c"},
{"id": "98c8ec04-54e3-40bb-b256-35ebb5c15280"}
],
"type": "outbound",
"to": "9999999",
"status": "new",
"scheduled_at": null,
"expires_at": null,
"processed_at": null,
"object": "sms",
"location": null,
"inserted_at": "2017-09-28T08:28:39.132037",
"id": "3203283d-7a98-49ad-a8d4-17b45a8373b8",
"from": "15550555055",
"encoding": 3,
"delivery_receipt": 0,
"delivered_at": null,
"body": "hello world [..]"
},
"12342341234": {
"updated_at": "2017-09-28T08:28:39.132046",
"udh": {
"ref_num": 541,
"count": 3
},
"parts": [
{"id": "3322dcb5-d668-4148-b94c-3f4b3faf670e"},
{"id": "b5fe304f-374e-4558-95f7-4a3ffdfb7784"},
{"id": "fbfb2ddc-f7e4-42b5-9bb8-6778f6d45987"}
],
"type": "outbound",
"to": "12342341234",
"status": "new",
"scheduled_at": null,
"expires_at": null,
"processed_at": null,
"object": "sms",
"location": null,
"inserted_at": "2017-09-28T08:28:39.132038",
"id": "3322dcb5-d668-4148-b94c-3f4b3faf670e",
"from": "15550555055",
"encoding": 3,
"delivery_receipt": 0,
"delivered_at": null,
"body": "hello world [..]"
}
}
Encoding
In most cases, we handle the encoding for you: we efficiently transcode it to either fit ASCII, Latin-1 or UTF-16.
The API supports UTF-8. Characters outside of the Latin-1 set will set the encoding to UCS2 (i.e. UTF-16). You can override the encoding by using the force_encoding field instead.
Below is a table of all the encodings, however only a few are supported for the API.
| int | Description | Supported by API | Segment size (single / multipart) |
|---|---|---|---|
| 0 | SMSC Default (GSM 7 bit / GSM 3.38) | Yes | 160 / 153 |
| 1 | IA5 (CCITT T.50) / ASCII (ANSI X3.4) | No | |
| 2 | Octet unspecified (8-bit binary) | No | |
| 3 | Latin 1 (ISO-8859-1) | Yes | 140 / 134 |
| 4 | Octet unspecified (8-bit binary) | No | |
| 5 | JIS (X 0208-1990) | No | |
| 6 | Cyrillic (ISO-8859-5) | No | |
| 7 | Latin/Hebrew (ISO-8859-8) | No | |
| 8 | UCS2 / UTF-16 (ISO/IEC-10646) | Yes | 70 / 67 |
| 9 | Pictogram Encoding | No | |
| 10 | Music Codes (ISO-2022-JP) | No | |
| 13 | Extended Kanji JIS (X 0212-1990) | No | |
| 14 | Korean Graphic Character Set (KS C 5601/KS X 1001) | No |
Good to know: message scheduling can be specified for up to 2 years in advance. We guarantee up to the minute accuracy.
SMS message length
Messages have limited length and exceeding that length will cause message to split into multiple messages that need to be concatenated at the destination (as per GSM messaging standard).
| Encoding | 1 segment max length | Multi segment max length | Max segments |
|---|---|---|---|
| 0 | 160 | 153 | 6 |
| 3 | 140 | 134 | 5 |
| 8 | 70 | 67 | 6 |
Since multipart messages need to contain additional information on segment ordering and concatenation rules those segments can carry a little less information than single-segment messages.
Each segment is technically another SMS message.
Example request
Simple message sent from one number to another using only the required parameters.
{
"from": "12003004000",
"to": ["12003004001"],
"body": "This is a sample test SMS message"
}
curl -X POST https://sms.tsgglobal.world/messages \
-H "Authorization: Bearer <messaging_api_key>" \
-H "Content-Type: application/json" \
-d '{"from":"12003004000","to":["12003004001"],"body":"This is a sample test SMS message","registered_delivery":1}'