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:

• Delivery status updates
• New inbound messages for both SMS and MMS

---

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.

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.

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

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 Status	Description
queued	The message is queued up on Telnyx's side.
sending	The message is currently being sent to an upstream provider.
sent	The message has been sent to the upstream provider.
delivered	The upstream provider has confirmed delivery of the message.
sending_failed	Telnyx has failed to send the message to the upstream provider. Please reach out to our support if you have received this status.
delivery_failed	The upstream provider has failed to send the message to the receiver. Please reach out to our support if you have received this status.
delivery_unconfirmed	There is no indication whether or not the message has reached the receiver. Please reach out to our support if you have received this status

---

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

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.

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

192.76.120.192/27