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

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.

Send an SMS Message

SMPP

Last modified 1yr ago