Quickstart
Connect your agent, add an endpoint, then send a test message from WhatsApp.
1. Connect your agent
In the dashboard, connect your agent with its WhatsApp Agent API token. Keep the provider token in Unpoll; your bot uses a separate agent API key.
A new connection starts from its activation time. Updates WhatsApp timestamped before that cutoff are skipped: they are neither stored nor delivered. Resuming a paused agent sets a new cutoff at the time of resuming, so messages sent while paused are skipped too. Connecting or resuming is not a way to import old conversations.
2. Add your webhook endpoint
Set a public HTTPS URL in the agent's settings, for example:
https://your-server.example/webhooks/whatsappThe endpoint must use HTTPS on port 443 and resolve to public addresses. Private, loopback, and link-local destinations are refused, and redirects are not followed.
Save the signing secret shown once. Configure signature verification before testing. Keep the complete secret, including its unpoll_whsec_ prefix, as your receiver's HMAC key.
No endpoint, no delivery. Events ingested without an enabled endpoint are stored and shown in the dashboard, but no delivery is created. Adding or re-enabling an endpoint does not deliver those older events, and they cannot be manually redelivered. Finish endpoint setup before messaging the agent.
3. Message your agent from WhatsApp
Use the creator's WhatsApp account: the provider allows an agent to message only the person who created it.
Inspect the message.received event and its delivery in the dashboard. Your receiver should:
- Read bounded, untouched body bytes and verify the timestamp and signature before parsing JSON.
- Atomically deduplicate on the verified body's
idand durably store the event or queued work. - Return a
2xxresponse promptly, within the 10-second total delivery-attempt budget. Do bot work asynchronously after durable acceptance.
The complete event envelope and status receipts are described under webhooks. If delivery fails, inspect its attempts and retry policy.
4. Send a reply
Create a key in the agent's API keys tab. Use it on:
POST https://api.unpoll.cc/v1/agents/{id}/messages
Copy the received message's data.from unchanged into the send request's to field. A successful send means WhatsApp accepted the message; delivery and read receipts arrive later as message.status webhooks.