Rate limits and ordering
WhatsApp applies separate per-agent counters over a rolling 60-second window. Sending a reply does not consume the read-call or media-lookup allowance.
| Operation | Allowance |
|---|---|
| Text sends | 12 per minute per agent |
| Read receipts and typing calls | 12 per minute per agent, separately from sends |
| Received-media downloads | 12 media lookups per minute per agent, separately from sends and reads |
Going over the send or read allowance returns 429 rate_limited with Retry-After; nothing is sent by a rejected send. For media, 429 rate_limited means retry the download after that delay.
Per-instance pacing
Unpoll paces each agent on each API instance. With several instances, WhatsApp's own per-agent 429 is the final limit and is returned as the same 429 rate_limited. This is not a distributed Unpoll quota across all instances.
Send ordering
Sends for one agent go out one at a time inside an API instance, because WhatsApp does not guarantee ordering between concurrent sends. A send waits up to 10 seconds behind an earlier one, then returns 429 send_in_progress with Retry-After.
When order matters, wait for each send to return before starting the next. Do not rely on independent or concurrent requests reaching the same instance or arriving in the order you started them. A successful send means acceptance; later delivery/read status arrives in webhooks.
Request and download bounds
- Send and read request bodies are limited to 64 KiB; larger bodies return
413 body_too_large. - Text is limited to 4,096 characters, with at least one non-whitespace character.
- An agent can have up to 10 active API keys.
- Media files are capped at 16 MiB. Each API instance downloads at most 4 files at once; a request waits up to 10 seconds for a slot, then returns
503 unavailableif none is free.
See send fields and media downloads for validation details.
Paused agents
Sending and media downloads work while an agent is active or paused. Pausing stops polling for incoming updates, not your replies. Already queued webhook work is not undone by pausing.
Resuming sets a new activation cutoff. Messages WhatsApp timestamped while paused are not stored or delivered after resume; see known limitations.
See errors before retrying any send whose outcome is unknown.