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
        }
      ]
    },
    "conditions": [],
    "actions": [
      {
        "name": "request",
        "params": {
          "url": "{{yourWebhookURL}}",
          "method": "post",
          "json": true,
          "data": {
            "eventName": "messageStatusChanged",
            "eventData": {
              "chat": {
                "##provide": {
                  "provider": "chat",
                  "key": "chat"
                }
              },
              "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

Chat

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

messageStatus

number

The new status - see the status codes table above.

error

string | null

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

timestamp

number

When the status changed (Unix epoch milliseconds).

externalId

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"
      },
      "...": "..."
    },
    "messageStatus": 3,
    "error": null,
    "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

​Subscribe

​Payload

​How to identify the message

​Manage this subscription

Subscribe

Payload

How to identify the message

Manage this subscription