# 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 {% hint style="info" %} Authentication is done by passing your TSG Global API key via the Authorization header in the format "Authorization: Bearer \" (using the messaging API key specifically). API credentials can be found here: {% endhint %} ## Method ## Returns a single message. Useful for manually checking message status. `GET` `https://sms.tsgglobal.world/messages/` 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 ```json { "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 ```json { "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). ```json { "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 ```json { "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" } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tsgglobal.com/api-reference/programmable-sms/receive-an-sms-message.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.