TSG Global API Documentation
  • Get Started
  • ISO/IEC/SOC Certification
  • Staging Environment Access
  • API Reference
    • Programmable SMS
      • Send an SMS Message
      • Receive an SMS Message
      • Delivery Receipts (DLRs)
      • SMPP
        • Headers
        • Errors
    • Programmable MMS
      • Send an MMS Message
      • Receive an MMS Message
      • Receive DLRs
      • SMTP
    • Phone Numbers
      • Search For New Available Numbers
      • Add Number to Cart
      • Get Reserved Numbers In Cart
      • Remove Reserved Number From Cart
      • Checkout Numbers in Cart
      • Disconnect Number
      • Get Number Information
      • Manage Number for SMS & 10DLC
        • Enable SMS/10DLC on a Number
        • Disable SMS on a Number
        • Update inbound SMS webhook/URI
      • Manage Number for MMS
        • Enable MMS on a Number
        • Disable MMS on a Number
        • Update inbound MMS webhook/URI
      • Manage Number for Voice
        • List Destination Priority
        • Add Destination Priority
        • Update Destination Priority
        • Delete Destination Priority
      • Protect your phone number
        • TextProtect Webhook
      • Toll-free phone numbers - search & ordering
    • Data Services
      • CNAM Lookup
      • Lookup SMS Carrier
    • Reports
      • CDR Records
        • Get Count of CDR Records
        • Get CDR Records
    • Compliance & Identity
      • Business Identity & 10DLC (TNID v1)
      • Toll-Free Verified Sender (Order)
      • Short Code Submission (Order)
  • GraphQL API & Authentication
Powered by GitBook
On this page
  • Overview
  • Authentication
  • Method
  • Send an SMS message.
  • Encoding
  • SMS message length
  • Example request
  • Example Responses

Was this helpful?

  1. API Reference
  2. Programmable SMS

Send an SMS Message

PreviousProgrammable SMSNextReceive an SMS Message

Last updated 6 months ago

Was this helpful?

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:

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

### A single message was 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"
  }
}

### A 3-part multipart message was sent to 9999999 and 12342341234. ###

{
  "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 [..]"
  }
}  

The entire multipart message id (top level) and first part id (under parts) will always match.

Encoding

In most cases, we handle the encoding for you — we’ll 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

0

SMSC Default (GSM 7 bit / GSM 3.38)

Yes

1

IA5 (CCITT T.50)/ASCII (ANSI X3.4)

No

2

Octet unspecified (8-bit binary)

No

3

Latin 1 (ISO-8859-1)

Yes

4

Octet unspecified (8-bit binary)

No

5

JIS (X 0208-1990)

No

6

Cyrllic (ISO-8859-5)

No

7

Latin/Hebrew (ISO-8859-8)

No

8

UCS2/UTF-16 (ISO/IEC-10646)

Yes

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

68

6

Since multipart messages need to contain additional information on segment ordering and concatenation rules those segments can carry 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": ["120030040001"],
    "body": "This is a sample test SMS message"
}

Example Responses

A single message was 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"
  }
}

A 3-part multipart message was sent to 9999999 and 12342341234.

{
  "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":"2285c9b4-8b3e-4c72-a30d-a3481a68b6a5",
    "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": "2e6ed7eb-a16f-4e56-b9f2-f66000921da3",
    "from": "15550555055",
    "encoding": 3,
    "delivery_receipt": 0,
    "delivered_at": null,
    "body": "hello world [..]"
  }
}
https://customer-portal.tsgglobal.com/account