Known limitations
Read these constraints before relying on Unpoll for an integration. This service targets the WhatsApp Agent API, not a general WhatsApp messaging platform or the WhatsApp Business Cloud API.
No endpoint, no delivery
Events that arrive while the agent has no webhook endpoint, or while the endpoint is disabled, are stored and shown in the dashboard but never delivered. No delivery job is created for them.
Adding or re-enabling the endpoint does not send those older events, and they cannot be manually redelivered. Set your endpoint up before you start messaging the agent. This differs from an existing delivery that failed: a retained failed delivery can be redelivered.
Messages before activation or while paused are skipped
Connecting an agent sets its activation cutoff to the current time. Every resume sets a new cutoff at the time of resuming. Updates WhatsApp timestamped before that cutoff are neither stored nor delivered. This includes messages sent before the first connection and messages sent while paused.
Unpoll walks retained provider updates from an explicit cursor and filters by the provider's event timestamp; it does not import old conversations or backfill paused-period messages. The catch-up walk after connect or resume is bounded. If a very large backlog exhausts that walk, the agent waits for new traffic at the provider's head rather than promising a full replay of retained history.
Pausing stops new polling, not your replies or media downloads, and it does not undo webhook jobs that were already queued. See rate limits and ordering.
The automatic retry window is short
A delivery cycle has at most 8 attempts total and a 24-hour maximum retry horizon. That does not mean an attempt will happen throughout the day: without Retry-After, automatic retries typically end after roughly 1 to 3.5 minutes of persistent errors. Longer outages need manual redelivery from the dashboard while history is retained.
See responses and retries for retryable statuses, timing, and duplicate handling.
Text sends only; received media can be downloaded
The outbound API sends text replies and read receipts. Received media can be downloaded, but Unpoll does not send or upload media and provides no message templates. Media files are fetched from WhatsApp, not stored by Unpoll.
Creator-only messaging
WhatsApp allows an agent to message only the person who created it. Copy the received message's from into to unchanged. Other recipients return 403 recipient_not_allowed. Treat user:… IDs as opaque, not as phone numbers or permanent people.
Pacing is per API instance
Unpoll paces sends, read calls, and media lookups separately at 12 per minute per agent on each API instance. With multiple instances, WhatsApp's own per-agent limit is final and comes back as 429 rate_limited. Do not assume a distributed Unpoll rate limiter or ordering of concurrent requests across instances.
When send order matters, wait for each request to return before starting the next. Never blindly retry a send whose outcome is unknown; it may already have been sent. See errors.
No API-key access to history
Event history, delivery history, and manual redelivery require dashboard sign-in. Agent API keys authorize only their own agent's send, read, and media routes. They cannot call history or management routes.
History is retained for 7 days after delivery activity, or 7 days after ingestion for an event without a delivery. Deleted history cannot be redelivered. See event history.
No signing-secret overlap on rotation
A rotated webhook secret replaces the old one immediately, including for newly prepared queued retries. There is no dual-secret overlap period; an already prepared or in-flight request may still use the prior configuration. Coordinate the receiver update and redeliver retained failures if necessary.
See verifying signatures for the exact key bytes, required validation, and atomic deduplication.