Overview
WhatsApp's Agent API exposes updates through long polling. Unpoll turns those updates into signed webhooks and gives your bot an API for replies.
WhatsApp Agent API → Unpoll → your HTTPS endpoint
Messages and status updates arrive from WhatsApp. Unpoll polls, persists, and delivers them; your receiver verifies, deduplicates, and accepts them. Polling is independent of webhook delivery, so a slow or broken endpoint does not block ingestion.
What Unpoll handles
- Continuous polling and cursor recovery, with one active provider poll per agent.
- Durable events and delivery jobs before committing cursor progress.
- Signed delivery, bounded retries, and attempt logs.
- Provider calls using your encrypted WhatsApp token.
What your application handles
- A public HTTPS endpoint.
- Signature verification and atomic deduplication.
- Durably storing accepted events or queued work, then acknowledging promptly.
- Bot logic and text replies using an agent API key.
Delivery is at least once, not exactly once. The same event can arrive more than once, and events can arrive out of order. Read responses and retries before processing side effects.
Three credentials, three purposes
| Credential | Purpose |
|---|---|
| WhatsApp Agent API token | Connects the agent. Unpoll stores it encrypted and uses it for provider calls; your bot does not need it. |
| Webhook signing secret | Verifies deliveries to your endpoint. Keep the full secret on your receiving server. |
| Agent API key | Authorizes that agent's send, read, and media requests. Keep it on your bot's server. |
Do not substitute one credential for another, expose them in client-side code, or log them.
API conventions
| Convention | Value |
|---|---|
| API base URL | https://api.unpoll.cc |
| Dashboard | app.unpoll.cc |
| Versioning | API routes start with /v1. Webhook bodies carry a version, currently 2026-10-01. |
| Format | JSON, UTF-8, for API requests and JSON responses; the media download route returns file bytes. |
| Unpoll IDs | UUID strings. |
| WhatsApp IDs | Message IDs (wamid) and user:… participant IDs are opaque strings. Store and send them back unchanged; do not interpret them as phone numbers or permanent people. |
| Unpoll timestamps | RFC 3339 in UTC, preserving fractional seconds, for example 2026-10-19T12:34:56.123456Z. |
| WhatsApp timestamps | The provider's timestamp fields are Unix seconds represented as strings. |
This is an integration with the WhatsApp Agent API, not the WhatsApp Business Cloud API. In particular, an agent may message only its creator, and Unpoll's send API supports text, not media or templates.