Receive an SMS Message

Fetch a message by ID for testing, register an inbound SMS webhook, and understand the message and delivery-receipt objects TSG posts to it.

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

Method

Returns a single message. Useful for manually checking message status.

GET https://sms.tsgglobal.world/messages/<uuid>

You can either use a message id, or one of the part ids. In the case of the latter, you will see detailed information about the part (the raw SMS).

We don’t recommend using this endpoint - perhaps only for testing. For production traffic, we recommend registering a webhook (see below).

Path Parameters

Name	Type	Description
uuid*	String	The UUID for the message ID you are wanting to query.

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

Register the webhook URL with Update inbound SMS webhook/URI. The 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.

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