This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuDocs
Docs
Close Sidemenu

Receiving Webhooksreceiving-webhooks

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:


Requirementsrequirements

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 HTTPSTelnyx Developers (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.

Hierarchy of URLshierarchy-of-urls

If webhooks are provided in the request bodyAPI, 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.

Delivery Status Updatesdelivery-status-updates

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

Delivery Status Payloaddelivery-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": "+17783005000",
      "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"
  }
}

Delivery Statusesdelivery-statuses

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

Incoming Messagesincoming-messages

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 profileAPI.

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 or using the ReportsAPI API endpoint.

Incoming Message Payloadincoming-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": "+1773005000",
      "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: 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 IPstelnyx-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

Was this page helpful?was-this-page-helpful