Skip to main content

Receiving Webhooks for Telnyx Messaging

You can choose to be notified about events on your SMS-capable long code or toll-free phone number by configuring webhooks.

Telnyx supports notifications for the following event types:


Requirements For enabling SMS notifications

For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.

Hierarchy of URLs

If webhooks are provided in the request body, we will use those, otherwise if the profile has webhooks, we’ll use those. If neither has webhooks, we won’t attempt a webhook delivery.

SMS delivery status updates

The Telnyx Messaging Services will attempt to notify you about each status update based on the hierarchy of URLs above.

Delivery status Payload

Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a message through a Telnyx long code to a T-Mobile long code:

{
"data": {
"event_type": "message.finalized",
"id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
"occurred_at": "2019-12-09T21:32:14.148+00:00",
"payload": {
"completed_at": "2019-12-09T21:32:14.148+00:00",
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "T-Mobile USA",
"line_type": "Wireless",
"phone_number": "+13125000000",
"status": "webhook_delivered"
},
"id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
"media": [],
"messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
"organization_id": "9d76d591-1b7d-405d-8c64-1320ee070245",
"parts": 1,
"received_at": "2019-12-09T21:32:13.552+00:00",
"record_type": "message",
"sent_at": "2019-12-09T21:32:13.596+00:00",
"tags": [],
"text": "Hello there!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+13125000000",
"status": "delivered"
}
],
"type": "SMS",
"valid_until": "2019-12-09T22:32:13.552+00:00",
"webhook_failover_url": "",
"webhook_url": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
}
}
Note

After pasting the above content, Kindly check and remove any new line added

Delivery statuses

Delivery StatusDescription
queuedThe message is queued up on Telnyx's side.
sendingThe message is currently being sent to an upstream provider.
sentThe message has been sent to the upstream provider.
deliveredThe upstream provider has confirmed delivery of the message.
sending_failedTelnyx has failed to send the message to the upstream provider. Please reach out to our support if you have received this status.
delivery_failedThe upstream provider has failed to send the message to the receiver. Please reach out to our support if you have received this status.
delivery_unconfirmedThere is no indication whether or not the message has reached the receiver. Please reach out to our support if you have received this status

Incoming messages to your numbers

Telnyx gives you the option of using webhooks to notify you of new inbound messages to your SMS-capable long code and toll-free phone numbers. This feature is enabled by configuring the incoming webhooks on the associated messaging profile.

Note

Regardless of whether you have configured webhook delivery, records of your received messages are still available in your reports, accessible in the Mission Control Portal

Incoming message Payload

Here is an example of a webhook event where a Telnyx Long Code receives a text message from a T-Mobile long code:

{
"data": {
"event_type": "message.received",
"id": "b301ed3f-1490-491f-995f-6e64e69674d4",
"occurred_at": "2019-12-09T20:16:07.588+00:00",
"payload": {
"completed_at": null,
"cost": null,
"direction": "inbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "T-Mobile USA",
"line_type": "long_code",
"phone_number": "+1312500000",
"status": "webhook_delivered"
},
"id": "84cca175-9755-4859-b67f-4730d7f58aa3",
"media": [],
"messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
"organization_id": "47a530f8-4362-4526-829b-bcee17fd9f7a",
"parts": 1,
"received_at": "2019-12-09T20:16:07.503+00:00",
"record_type": "message",
"sent_at": null,
"tags": [],
"text": "Hello from Telnyx!",
"to": [
{
"carrier": "Telnyx",
"line_type": "Wireless",
"phone_number": "+1773005000",
"status": "webhook_delivered"
}
],
"type": "SMS",
"valid_until": null,
"webhook_failover_url": null,
"webhook_url": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
}
}
Note

After pasting the above content, Kindly check and remove any new line added

Note

MMS media links will be available for 30 days after message receipt. After 30 days the link will expire and the media will no longer be available through Telnyx.

Telnyx Webhook IPs

If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s):

192.76.120.192/27