Messages Failed to Deliver

ubscribe to receive a notification whenever an outgoing message fails to deliver (status code 4 or 5) - for example blocked by Meta/WhatsApp, invalid number, or network failure. Event name: messageFailed\ Required token scopes:

Create scenarios
Manage scenarios on behalf of user

see Authentication Send the body below to Import Subscription. You only need to change:

url (required) - Located under data.actions[0].params.url. Replace {{yourWebhookURL}} with the destination URL that should receive the events.
asStatus - Keep "active" to enable the subscription immediately, or "inactive" to save it as an inactive revision.

Import body

{
  "data": {
    "version": "v1",
    "name": "(SUB) Messages Failed to Deliver",
    "description": "Sends a webhook when an outgoing message fails to deliver (blocked by Meta)",
    "triggerEvents": [
      "app.message.statusRequest"
    ],
    "loaders": {
      "afterConditions": [
        {
          "name": "chat",
          "alias": "chat",
          "params": {
            "name": {
              "##provide": {
                "provider": "messageStatusRequest",
                "key": "chat.name"
              }
            },
            "accountId": {
              "##provide": {
                "provider": "messageStatusRequest",
                "key": "chat.accountId"
              }
            },
            "idByChannel": {
              "##provide": {
                "provider": "messageStatusRequest",
                "key": "chat.id"
              }
            }
          },
          "confidentialData": false
        }
      ]
    },
    "conditions": [
      [
        {
          "name": "compare",
          "params": {
            "comparison": "Equal",
            "compareTo": 4,
            "value": {
              "##provide": {
                "provider": "messageStatusRequest",
                "key": "status"
              }
            }
          },
          "confidentialData": false
        }
      ],
      [
        {
          "name": "compare",
          "params": {
            "comparison": "Equal",
            "compareTo": 5,
            "value": {
              "##provide": {
                "provider": "messageStatusRequest",
                "key": "status"
              }
            }
          },
          "confidentialData": false
        }
      ]
    ],
    "actions": [
      {
        "name": "request",
        "params": {
          "url": "{{yourWebhookURL}}",
          "method": "post",
          "json": true,
          "data": {
            "eventName": "messageFailed",
            "eventData": {
              "chat": {
                "##provide": {
                  "provider": "chat",
                  "key": "chat"
                }
              },
              "error": "%messageStatusRequest:error%",
              "timestamp": "%messageStatusRequest:timestamp%",
              "externalId": "%messageStatusRequest:ids%"
            }
          }
        },
        "confidentialData": false
      }
    ],
    "options": {
      "unorderedActions": false
    }
  },
  "asStatus": "active"
}

A 201 response returns your new subscription - save its _id to manage it later. You can also add an optional authorUid root field (a Texter user UID) to attribute the subscription to a specific user.

Payload

When the event fires, your URL receives an HTTP POST with eventName: "messageFailed" and the following eventData:

Chat

The chat associated with the failed message. See the Chat object for all fields.

string

The error message or code received from the provider.

number

When the failure occurred (Unix epoch milliseconds).

string[]

Unique IDs assigned to the message(s) by the external provider (e.g. WhatsApp wamid...).

Example payload

{
  "eventName": "messageFailed",
  "eventData": {
    "chat": {
      "_id": "69072b0233aea8a47f8bad9f",
      "hasMessageError": true,
      "title": "972521234567",
      "...": "..."
    },
    "error": "Message undeliverable\nMessage Undeliverable.",
    "timestamp": 1768141074000,
    "externalId": [
      "wamid.HBgMOTcyNTIxMjM0NTY3FQIAERgSMDhGRTVGNEY1MTA0Q0NBMzNEAA=="
    ]
  }
}

How to identify the message

Because this event is triggered by the external provider (e.g. Meta/WhatsApp), the payload does not contain the internal message._id. Instead, it provides the externalId. To find the specific message in your system:

Take the _id from the chat object in the payload.
Call Get Messages of a Chat.
Find the message whose channelInfo.id matches one of the values in the externalId array.

Manage this subscription

Action	Endpoint
List subscriptions	List All Subscriptions
Pause	Inactivate Subscription
Resume	Activate Subscription
Delete	Delete Subscription
Debug executions	List Scenario Runs

Getting Started

Endpoints

Webhooks

Objects

Messages Failed to Deliver

Payload

How to identify the message

Manage this subscription

​Subscribe

​Payload

​How to identify the message

​Manage this subscription

Subscribe

Payload

How to identify the message

Manage this subscription