Message Detail Records' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Once a send message API request goes through, your SMS or MMS will be put into a queue to be sent to its destination. A Message Detail Record (MDR) describes a specific message request and includes those that are active, pending and completed. Telnyx stores the most recent version of the MDR.
To get the details of a message, make an HTTP GET request to the API by passing the message UUID. The UUID is returned by the send message request as the sms_id
.
The example below shows the status updates received for a message that was sent with these details:
- Callback URL: https://example.com/campaign/7214
- ID of request: 834f3d53-8a3c-4aa0-a733-7f2d682a72df
Note: Response payload lists status as "sending"
Response 1: Payload SENT
{
"sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
"sms_gw_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
"user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
"profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"status": "sent",
"delivery_status": "",
"date_created": "2018-03-26T20:53:16.061000",
"date_updated": "2018-03-26T20:53:16.060000",
"created": 1522097596060,
"updated": 1522097596061,
"body": {
"coding": 3,
"num_chars": 6,
"text": "Hello!",
"text_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"num_bytes": 6,
"bytes_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"parts": 1
},
"from": "+18445550001",
"to": "+18665550002",
"direction": "outbound",
"on_net": false,
"cost": null,
"currency": null,
"type": "SMS",
"carrier": "T-MOBILE USA",
"line_type": "Wireless"
}
Response 2: Payload DELIVERED
{
"sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
"sms_gw_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
"user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
"profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"status": "delivered",
"delivery_status": "success",
"date_created": "2018-03-26T20:53:16.061000",
"date_updated": "2018-03-26T20:53:16.060000",
"created": 1522097596060,
"updated": 1522097596061,
"body": {
"coding": 3,
"num_chars": 6,
"text": "Hello!",
"text_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"num_bytes": 6,
"bytes_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"parts": 1
},
"from": "+13125550001",
"to": "+13129450002",
"direction": "outbound",
"on_net": false,
"cost": "0.00450",
"currency": "USD",
"type": "SMS",
"carrier": "T-MOBILE USA",
"line_type": "Wireless"
}
Retrieving an MDR' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
curl -X GET \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "x-profile-secret: YOUR_MESSAGING_PROFILE_SECRET" \
"https://sms.telnyx.com/messages/834f3d53-8a3c-4aa0-a733-7f2d682a72df"
Response Payload
{
"sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
"sms_gw_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
"user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
"profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"status": "delivered",
"delivery_status": "success",
"date_created": "2018-03-26T20:53:16.061000",
"date_updated": "2018-03-26T20:53:16.060000",
"created": 1522097596060,
"updated": 1522097596061,
"body": {
"coding": 3,
"num_chars": 6,
"text": "Hello!",
"text_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"num_bytes": 6,
"bytes_hash": "334d016f755cd6dc58c53a86e183882f8ec14f52fb05345887c8a5edd42c87b7",
"parts": 1
},
"from": "+13125550001",
"to": "+13129450002",
"direction": "outbound",
"on_net": false,
"cost": "0.00450",
"currency": "USD",
"type": "SMS",
"carrier": "T-MOBILE USA",
"line_type": "Wireless"
}
MDR Schema and Status Descriptions' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
A Message Detail Record (MDR) describes a specific message request and includes those that are active, pending and completed. Telnyx stores the most recent version of the MDR.
MDR Schema
|
ID of the message request, which is a UUID. It is included as a string in the POST /messages response payload for outbound messages, or the payload of an incoming webhook for inbound messages. e.g., `"c51c89d9-68ad-4db2-a471-cf622d21c40d"` |
|
Typically used only in discussions with Telnyx Support. The value is `""` (an empty string) in the POST /messages response payload because it is unassigned at that time. In certain cases, the `sms_id` and gateway ID will be the same (e.g., messages sent between two Telnyx phone numbers). |
user_id |
ID of the user who owns the sending phone number, represented as a stringified UUID. |
profile_id |
ID of the Messaging Profile to which the sending phone number is assigned, represented as a stringified UUID. |
body |
See § MDR body field scheme. |
|
Please note that See § status and §delivery_status. |
|
Created/updated at time in Unix time in milliseconds, returned as a 13-digit integer (`1 ms = 10-3 sec)`. e.g., `1522097596060` is Mon, 26 Mar 2018 20:53:16 UTC |
|
Created/updated at date and time in ISO 8601 in UTC. The format of the string returned is `YYYY-MM-DDTHH:MM:SS.mmmmmm`. |
from |
Receiver's +E.164 formatted phone number, represented as a string. |
to |
Sender's +E.164 formatted phone number, represented as a string. |
direction |
Options: [`"inbound"`, `"outbound"`] |
on_net |
Whether the message stayed within the Telnyx network Options: [`true`, `false`] |
carrier |
Indicates the carrier name for the number you're sending to or receiving from |
line_type |
Indicates the type of number you're sending to or receiving from Options: [`"Wireline"`, `"Wireless"`, `"VoIP"`] |
|
Default: `null` `null` means that the amount/currency was unknown when the MDR was cut and that the field will be populated later. This is commonly seen in MDRs posted to the delivery status webhook. |
type |
Type of messaging service e.g., `"SMS"` = text message |
MDR Body Field Schema' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
|
Default: 3 `0` = GSM 7-bit `3` = ISO 8859-15 (a.k.a., Latin-9) `8` = UCS 2/UTF 16 BE |
num_chars |
Number of characters in the decoded byte payload. |
text |
Message body (i.e., content) as a non-empty string. |
num_bytes |
Number of bytes in the message payload. |
bytes_hash |
SHA256 hash of the raw bytes sent over SMPP. |
text_hash |
SHA256 hash of the message encoded in UTF-8. |
parts |
Number of parts into which the message body must be split. |
MDR Status Field' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
status
describes the status/state of the message request when the MDR was retrieved. The value is a string without whitespace.
Inbound Status
When you request an MDR for an inbound message request, the status
of the retrieved MDR will most likely be "delivered". That said, there are two inbound statuses:
`"received"` | Received by the Telnyx Messaging Services. |
`"delivered"` | Transmitted to you, after receipt. |
Outbound Status
For an outbound message request:
- An MDR is only created when Telnyx attempts to send the message. A rejected request will not have an associated MDR. When a request is rejected, Telnyx responds with the reason e.g., missing or invalid value.
- If the request includes a reachable delivery status webhook URL, we'll POST the MDR after each status update.
- Telnyx stores the most recent version of the MDR.
- The
status
of a completed request is either "delivered" or "failed", which are the "finished" statuses.
An accepted request will transition through some, but not all, of the following:
`"sending"` | Released from scheduler and submitted to gateway. [Queued in scheduler, due to outbound rate limiting.] |
`"gw_timeout"` | No DLR (delivery receipt) from gateway. |
`"sent"` | Success DLR received from gateway. Message has been sent downstream. |
`"dlr_timeout"` | No DLR from downstream. |
`"delivered"` | To the best of our knowledge, the message was delivered. |
`"failed"` | Failure DLR from gateway or downstream, which is notification of message delivery failure. |
MDR Delivery Status Field' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Please note that status
(not delivery_status
) describes the status of a message request.
delivery_status
is used to pass back to you miscellaneous information. The information often relates to the delivery status webhook.
Examples
`""` |
Default Field unused at time of request |
`"success"` | No known errors occurred while posting delivery status updates |
`"failure"` | The inverse of `"success"`. Example cause: The delivery status webhook was configured but unreachable. |