async: true, the API queues the command, responds immediately with a
commandId, and executes it in the background.
The result arrives in two ways, both with the same payload:
command.resultwebhook: the API notifies your system when the command finishes. This is the guaranteed delivery channel.- Query by
commandId:GET /api/v1/commands/{commandId}, useful for debugging or as a complement. The result expires after about 1 hour.
Flow
1
Send the command with async: true
2
Store the commandId from the response
The API responds
200 immediately, before executing the command:success: true here only means the command entered the queue. It does
not yet tell you whether it succeeded.3
Receive the result on the webhook
When the command finishes, successfully or not, the API sends one
command.result event with the same commandId.Enabling asynchronous mode
Sendasync in the body (JSON) or in the query string, on GET routes. The
field accepts a boolean (true) or a string ("true" or "1"). When absent
or false, the command is synchronous as usual.
Official API sessions (
cloud_api) ignore async and always respond
synchronously: the send goes straight through Meta, with no queue.Queueing response
Message sending routes also returnsessionId, to, and messageType.
If the API cannot queue the command, it responds with an error and the command
is not executed. In that case it is safe to try again.
Supported routes
Messages
Messages
Groups
Groups
Contacts and chats
Contacts and chats
Labels, catalog, channels, history, and media
Labels, catalog, channels, history, and media
command.result webhook
Configuration
The commands webhook is account-level: one URL receives the result of every asynchronous command from every session in the account. It is separate from each WhatsApp session’s event webhooks. In the Dashboard, go to Integrations → Commands Webhook and provide:- URL:
https://endpoint that will receive the events. - Secret (optional, recommended): enables the
X-DAPI-Signaturesignature. - Active: without it, no event is sent.
GET /api/v1/account/webhooks lists the current configuration, with
hasSecret in place of the secret.
Envelope
Failure example
A command that executed and failed, or that hit the timeout, also produces acommand.result, with success: false:
The
error text comes from WhatsApp or from the execution layer and may
change. Use success to drive your flow and treat error as a log message.Headers
Validating the signature
Compute the HMAC over the raw body received, not over the re-serialized JSON, and compare it with the header using a constant-time comparison:Execution and delivery guarantees
One result per command
One result per command
Each asynchronous command produces exactly one
command.result: with
success: true if it succeeded or success: false if it failed or hit the
timeout.The command is never re-executed
The command is never re-executed
If the command fails, the API does not retry it: many commands, such as
sending a message, cannot be repeated without risk of duplication.
Resending is up to you, after reading the
error.Webhook delivery is retried
Webhook delivery is retried
The webhook goes out through a durable queue. Your endpoint must respond
2xx within 30 seconds. Otherwise, delivery is retried with exponential
backoff (15 s, then 30 s), for up to 3 attempts in total.404or410stop the attempts immediately: the endpoint is treated as nonexistent.- An endpoint that fails repeatedly has delivery suspended for a while (circuit breaker), to avoid piling up useless attempts.
- Respond
200as soon as you validate the signature and process the event afterwards, in your own queue. - Store the
commandIdat send time, alongside your system’s entity (order, conversation, notification), so you can match the result later. - Do not rely on the arrival order of webhooks. Commands run in parallel and may finish in a different order than they were sent.
Querying by commandId
GET /api/v1/commands/{commandId} shows the current state of the command,
whether it is still queued, running, or already finished, and includes the same
webhook payload in result. Details in
Get asynchronous command.
The result can be queried for about 1 hour after execution (24 hours if
the worker fails). After that, the query responds
404.Delivery order (sequential)
Asynchronous commands run in parallel. Two consecutive sends to the same contact may arrive out of order: a heavy image may go out after the text sent right after it. For message sends, addsequential: true along with async: true. Sends to
the same recipient go out one at a time, in the order they reached the API.
Each one still produces its own command.result. See
Ordered asynchronous sending.
