Message Lifecycle

Message statuses

Every message sent through Zapster goes through a lifecycle with well-defined statuses. The table below lists all the possible ones:

Status	Description	When it happens
`pending`	Immediate message being processed	When you send without `send_at`
`scheduled`	Scheduled, waiting for its send time	When you send with `send_at`
`sent`	Successfully delivered to WhatsApp	Send confirmed by the instance
`failed`	Send failed	After 3 unsuccessful attempts
`canceled`	Canceled by the user	When you call `DELETE /v1/wa/messages/:id`

Once a message reaches sent, failed, or canceled, the status is final. It does not change again.

Timestamps

Beyond the status, each message carries timestamps that show what happened and when. Not all of them are filled in on every message: it depends on the send type and on what happened afterward.

Field	Filled in when	Note
`created_at`	The message is created	Always present
`send_at`	Set by the user	Only exists on scheduled messages
`sent_at`	The message is sent successfully	Filled in when WhatsApp accepts the send
`delivered_at`	Delivery is confirmed on the device	When the message reaches the recipient’s phone
`read_at`	The recipient reads the message	When the recipient opens the conversation
`canceled_at`	The message is canceled	When the user calls `DELETE` before sending

About delivery and read receipts

The delivered_at and read_at fields depend on factors outside Zapster’s control:

If the recipient turned off read receipts in their WhatsApp settings, read_at will never be filled in.
If the recipient’s phone has no internet, delivered_at may lag until they come back online.
These fields do not change the message status. Once the status is sent, it stays sent. Delivery and read are extra pieces of information, recorded only in the timestamps.

In practice, you can use delivered_at and read_at to build delivery and read reports, but do not rely on them for critical flows. Not every recipient will generate these events.

When a message fails

If a message has the status failed, the errors field carries a list with the details of what went wrong. The error structure varies a bit depending on the instance type. For official (WABA) instances, errors includes Meta’s error code and a direct link to their documentation:

{
  "errors": [
    {
      "code": 131047,
      "title": "Re-engagement message",
      "details": "More than 24 hours have passed since the recipient's last reply.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
    }
  ]
}

Some common errors on WABA instances:

131047: The 24-hour window has expired. The recipient did not reply in the last 24h and you tried to send a non-template message.
132000: Template not found. Check that the template name and language are correct.
131026: The number is not on WhatsApp or is invalid.

For unofficial (QR code) instances, the most common errors are:

The instance is offline (the phone lost connection or the session expired).
The number is blocked or does not exist on WhatsApp.
The WhatsApp send limit was reached.

In every case, the errors field carries enough information for you to understand what happened and decide whether it is worth trying again.

Introduction

Concepts

Guides

Message statuses

Timestamps

About delivery and read receipts

When a message fails

​Message statuses

​Timestamps

​About delivery and read receipts

​When a message fails

Message statuses

Timestamps

About delivery and read receipts

When a message fails