Messages Failed to Deliver

Subscribe 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
        },
        {
          "name": "chatMessages",
          "alias": "messages",
          "params": {
            "chatId": "%chat:_id%"
          },
          "confidentialData": false
        },
        {
          "name": "staticData",
          "alias": "messageLookup",
          "params": {
            "data": {
              "externalId": "%messageStatusRequest:ids.0%",
              "messages": "%messages:latest(5,-1,\"out\")%"
            }
          },
          "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",
                  "transform": [
                    {
                      "name": "omit",
                      "args": [
                        "crmData",
                        "previousBotSession"
                      ]
                    }
                  ]
                }
              },
              "messageId": {
                "##provide": {
                  "provider": "messageLookup",
                  "key": "data",
                  "keyArgs": [],
                  "transform": [
                    {
                      "name": "hbTpl",
                      "args": [
                        "[{{#each messages}}{{#if ../externalId}}{{#when channelInfo.id 'eq' ../externalId}}\"{{_id}}\",{{/when}}{{/if}}{{/each}}null]"
                      ]
                    },
                    {
                      "name": "jsonParse",
                      "args": []
                    },
                    {
                      "name": "get",
                      "args": [
                        "0"
                      ]
                    }
                  ]
                }
              },
              "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 message, excluding crmData and previousBotSession. See the Chat object for the remaining fields.

string | null

The Texter message _id matched to externalId[0]. This is the same messageId returned by Send Template Message. Returns null when no match is found among the latest 5 outgoing messages.

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",
      "...": "..."
    },
    "messageId": "690883c5962e17ab3033f92f",
    "error": "Message undeliverable\nMessage Undeliverable.",
    "timestamp": 1768141074000,
    "externalId": [
      "wamid.HBgMOTcyNTIxMjM0NTY3FQIAERgSMDhGRTVGNEY1MTA0Q0NBMzNEAA=="
    ]
  }
}

How to identify the message

Use messageId to match this event to the messageId returned by Send Template Message. The subscription searches the latest 5 outgoing messages in the chat. It selects the message whose channelInfo.id equals the first value in externalId. If no match exists, messageId is null; the status webhook is still sent. externalId keeps all provider IDs from the event. The single messageId identifies only externalId[0]. For older messages or additional IDs, use Get Messages of a Chat, page through the results, and match each channelInfo.id.

Existing subscriptions keep their saved scenario. Update your subscription to use this template before expecting the messageId field and the chat-field omissions.

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