Skip to main content
By default, the API only responds after WhatsApp executes the command. Sending heavy media, for example, holds the request until the message goes out. With 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.result webhook: 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

Send async 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

string
required
Command UUID. It is the key to correlate with the webhook and to query the status.
boolean
required
Always true in this response: the command was accepted into the queue.
string
required
Always "queued".
string
required
Always "Command queued".
string
required
Time of queueing in ISO 8601 (UTC).
Message sending routes also return sessionId, 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

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-Signature signature.
  • Active: without it, no event is sent.
You can also configure it through the API:
GET /api/v1/account/webhooks lists the current configuration, with hasSecret in place of the secret.
Without a commands webhook configured and active, the asynchronous command executes normally, but the result is not sent anywhere. It is only available through the query by commandId, during the retention window.

Envelope

string
required
Always "command.result".
string
required
Always "command".
string
required
Time the webhook was generated, in ISO 8601 (UTC).
object
required
Command result.

Failure example

A command that executed and failed, or that hit the timeout, also produces a command.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

Each asynchronous command produces exactly one command.result: with success: true if it succeeded or success: false if it failed or hit the timeout.
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.
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.
  • 404 or 410 stop 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.
Because of retries, the same command.result may arrive more than once. This happens, for example, if your endpoint processes the event but responds after 30 seconds. Treat the commandId as an idempotency key and ignore repeats.
Best practices for your endpoint:
  • Respond 200 as soon as you validate the signature and process the event afterwards, in your own queue.
  • Store the commandId at 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, add sequential: 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.

Common errors