Receive an SMS Message
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 is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer <api_key>"
get
https://sms.tsgglobal.world/messages/<uuid>
Returns a single message. Useful for manually checking message status.
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
}
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.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"
}
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. |
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. |
{
"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"
}
}
Last modified 1yr ago