Message lifecycle

Every outbound message moves through a small state machine. Knowing the status tells you what you can still do and which webhook to expect.

schedule (optional)          send
pending ──► sent|failed|expired|cancelled
                │
                ▼
            queued ──► sent ──► delivered ──► read / played
                         │
                         └──► failed

Scheduled message statuses

When you pass send_at on POST /v1/messages, LazyApp stores a scheduled row and returns 202 instead of sending immediately.

Status	Meaning
`pending`	Waiting for `send_at` (or still retrying after a transient failure)
`sent`	Dispatched; the linked message now carries delivery status
`failed`	Could not be sent after attempts
`expired`	Past `ttl_seconds` / expiry before it could go out
`cancelled`	Cancelled with `DELETE /v1/messages/scheduled/{id}`

List with GET /v1/messages/scheduled. Cancel while pending.

Message statuses

After accept (or after a schedule fires), the message row uses:

Status	Meaning	Typical webhook
`queued`	Accepted; waiting on the provider path	—
`sent`	Provider accepted it	`message.sent`
`delivered`	Reached the contact’s device	`message.delivered`
`read`	Contact opened it	`message.read`
`played`	Contact played voice/video note	`message.read` / media-specific
`failed`	Terminal failure	`message.failed`

POST /v1/messages returning 201 means accepted, not delivered. Poll GET /v1/messages/{uuid} only for debugging; subscribe to webhooks in production.

Which status a new message gets

You send	Initial result
No `send_at`	Message created; response is `201` with status typically `queued` or already `sent` / `failed` if the provider answered synchronously
`send_at` in the future	Scheduled row; response is `202` with status `pending`

There is no draft or multi-platform partial state — one send targets one WhatsApp number and one contact.

What you can do

Operation	When
Cancel schedule	While the scheduled row is `pending`
Fetch message	Any time after accept, by LazyApp uuid
Download inbound media	After `message.received` with media
Retry a failed schedule	Create again with a new `Idempotency-Key` / body key — there is no separate retry endpoint
Unpublish / edit delivered	Not supported by WhatsApp Cloud API for business-sent messages

There is no unpublish: WhatsApp does not let you delete another person’s delivered message via the business API the way some social networks do. Contacts can delete for themselves; you may see message.deleted when coexistence reports a revoke.

Tracking with webhooks

Event	Fires when
`message.sent`	Provider accepted the outbound message
`message.delivered`	Delivered to the device
`message.read`	Opened (or played, for some media)
`message.failed`	Terminal failure; read `error_message`
`message.received`	Inbound from a contact
`message.deleted`	Revoke / delete reported

See Webhook events for payload shapes.

Scheduling and timezones — how send_at is interpreted
Idempotency — safe retries on create
Errors — refusals vs async failure

Getting started

Core concepts

WhatsApp

Security

Billing

Sending

Receiving

Platforms

Migrating

Reference

Message lifecycle

Scheduled message statuses

Message statuses

Which status a new message gets

What you can do

Tracking with webhooks

​Scheduled message statuses

​Message statuses

​Which status a new message gets

​What you can do

​Tracking with webhooks

​Related

Scheduled message statuses

Message statuses

Which status a new message gets

What you can do

Tracking with webhooks

Related