Receive an SMS Message

Overview

Receive inbound SMS messages to your numbers. Get your message returned via SMPP or via a webhook URL that you provide. For production traffic, we don’t recommend using this endpoint, but instead registering a webhook.

Authentication

Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer <api_key>"

Method

get
https://sms.tsgglobal.world/messages/<uuid>
Returns a single message. Useful for manually checking message status.

Example Responses

Single message
{
"id": "03b4641f-17a6-4565-bdba-1ce905be3312",
"type": "outbound",
"from": "12341234",
"to": "12342341234",
"object": "sms",
"body": "hello"
"encoding": 3,
"delivery_receipt": "no",
"status": "new",
"location": null,
"inserted_at": "2017-09-17T19:12:32.792699",
"updated_at": "2017-09-17T19:12:32.792704",
"scheduled_at": null,
"processed_at": null,
"delivered_at": null,
"expires_at": null
}
Longer message consisting of multiple UDH parts
{
"id": "0ab46aaa-17a6-a5a5-7dba-1ce905be3312",
"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",
"from": "12341234",
"to": "12342341234",
"object": "sms",
"body": "hello this is an extremely long message that spans 3 actual SMS messages sent from the carrier to the user. The phone will reassemble all of these messages into one longer, single message. We're currently at 2 parts, but let's keep going until we hit 3 parts. At a simple text message (no emoji), that will probably be around 3*140 characters, encoded as latin-1",
"encoding": 3,
"delivery_receipt": "no",
"status": "new",
"location": null,
"inserted_at": "2017-09-17T19:12:32.792699",
"updated_at": "2017-09-17T19:12:32.792704",
"scheduled_at": null,
"processed_at": null,
"delivered_at": null,
"expires_at": null
}

Set your webhook URL for your Number

The new webhook will deliver both new messages as well as delivery receipts. You can distinguish the event type based on the object parameter (sms for messages, sms_dlr for delivery receipts).
Note: Webhook objects will also return Message objects, and include a parts section in the case of a UDH multi-part message.
Your webhook must return 200 OK HTTP status code to acknowledge the event, otherwise we’ll attempt to redeliver up to 17 times over 2-3 days (with exponential backoff).
{ "body": "Thank you for texting my webhook number!" }
You can optionally send back a JSON response with the body key, containing a message response (which will be encoded with the same encoding rules mentioned under the Message Send API) to be sent back to the originator. We currently only support the body key, but are evaluating adding encoding and other functionality supported by Message Send.Receive your Content.

Message Object

Represents a single message. This can be either one actual SMS, or more if the message was longer and split into multiple UDH parts.
This is done because of convenience for our users, generally it’s more important to track the status of a whole message, instead of individual parts. Note that you can still retrieve the number of parts sent (for billing purposes) etc., as well as view part information as needed.
If the low level SMS details are important (down to the PDU), then our SMPP API might be more suitable for you.
In the case of a single message, id, represents the actual sms id.
In the case of a multipart message, the id is representing all the parts. The object will also contain a parts section which will contain information about each of the individual sms parts that were sent. (currently just the part ids, you can use those to retrieve more information via the above Message Get API). To get the number of actual sms sent (in v1, that was the X-Message-Count header), you can either check the length of parts array, or check udh.count.
Below is an example of the package that will be sent to your webhook.
{
"body": "Test 4",
"delivered_at": null,
"delivery_receipt": "no",
"encoding": 3,
"expires_at": null,
"from": "14252437709",
"id": "0658b5fd-d36d-49ae-9e58-d0a7f053f1bb",
"inserted_at": "2022-04-06T21:49:29.926166",
"location": null,
"object": "sms",
"processed_at": null,
"scheduled_at": null,
"status": "new",
"to": "13462239287",
"type": "inbound",
"udh": {
"count": null,
"ref_num": null,
"seq_num": null
},
"updated_at": "2022-04-06T21:49:29.926166"
}

Delivery Receipts

Delivery Receipt Object

Name
Description
id
string Unique identifier for the object
type
string Message type, either inbound or outbound.
from
string Number (or sender ID) of the original sender
to
string Number of the message recipient
object
string Always set to sms_dlr.
delivery_status
string Delivery status.
submitted_at
timestamp Time at which the message was submitted
done_at
timestamp Time at which the message has reached it’s final state (minute accuracy, seconds ignored)
delivery_error_code
string If unsuccessful, will contain upstream error code.
inserted_at
timestamp Denotes when the message was initially received.
updated_at
timestamp Denotes when the data last changed.
sms.id
uuid ID of the matching SMS.

Delivery Status

Id
Description
delivered
Message was successfully delivered.
expired
Message validity period has expired (for instance, the phone was turned off).
deleted
Message has been deleted.
undelivered
Message is undeliverable (for instance the number doesn’t exist)
accepted
Message was accepted and will be sent.
unknown
Delivery status is unknown.
rejected
Message was rejected by the carrier
failed
Delivery was unsuccessful.
enroute
Message is enroute.
skipped
Message was skipped.

Example DLR

{
"id": "500fe938-fd2d-4dc1-a186-592e71112388",
"type": "inbound",
"from": "15678234",
"to": "12342341234",
"object": "sms_dlr",
"delivery_status": "delivered",
"delivery_error_code": "000",
"inserted_at": "2017-09-17T19:12:32.792699",
"updated_at": "2017-09-17T19:12:32.792704",
"submitted_at": "2017-06-01T18:00:00",
"done_at": "2017-06-01T18:00:05",
"sms": {
"id": "03b4641f-17a6-4565-bdba-1ce905be3312"
}
}