Message Status Changed

Subscribe to receive a notification whenever the status of an outgoing message changes, letting you track the full message lifecycle (e.g. “Sent” to “Delivered” to “Seen”). The messageStatus field contains one of:

Value	Meaning
`0`	Sent - sent from the platform
`1`	Accepted - accepted by the provider (e.g. Meta received it)
`2`	Delivered - delivered to the recipient’s device
`3`	Seen - read/opened by the recipient (blue ticks)
`4`	Failed - failed to deliver (e.g. invalid number)
`5`	Channel Failed - system/channel level failure
`6`	Deleted - message was deleted

Event name: messageStatusChanged 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 Status Changed",
    "description": "Sends a webhook for all outgoing messages status changes (e.g., from \"Delivered\" to \"Seen\")",
    "triggerEvents": [
      "app.message.statusRequest"
    ],
    "loaders": {
      "beforeConditions": [
        {
          "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": [],
    "actions": [
      {
        "name": "request",
        "params": {
          "url": "{{yourWebhookURL}}",
          "method": "post",
          "json": true,
          "data": {
            "eventName": "messageStatusChanged",
            "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"
                      ]
                    }
                  ]
                }
              },
              "messageStatus": "%messageStatusRequest:status%",
              "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: "messageStatusChanged" 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.

number

The new status - see the status codes table above.

string | null

Error message - only present when status is 4 or 5, otherwise null.

number

When the status changed (Unix epoch milliseconds).

string[]

Unique IDs assigned to the message(s) by the external provider.

Example payload

{
  "eventName": "messageStatusChanged",
  "eventData": {
    "chat": {
      "_id": "69072b0233aea8a47f8bad9f",
      "displayName": "Josh Dun",
      "channelInfo": {
        "name": "whatsapp",
        "id": "972521234567"
      },
      "...": "..."
    },
    "messageId": "690883c5962e17ab3033f92f",
    "messageStatus": 3,
    "error": null,
    "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

Message Status Changed

Payload

How to identify the message

Manage this subscription