Connect. Receive. Reply.

Authenticate API requests with an Unpoll customer API key in the Authorization header. This is separate from the WhatsApp token used to connect your agent and the signing secret used to verify webhooks.

Authorization: Bearer YOUR_API_KEY

A key can send through every agent in its workspace. Workspace owners create and revoke keys in the dashboard. The complete key is shown only at creation and cannot be retrieved later.

• Keep keys in server-side environment variables or a secret manager. Never put them in browser code, URLs, or logs.
• To rotate a key, create a replacement, update your application, then revoke the old key.
• Missing, invalid, or revoked keys return 401. An unavailable authentication service returns 503 with authentication_unavailable.

Google sign-in gives access to the dashboard. Its session cookie does not authenticate API requests.

Send a text message using the local agent UUID and a key from the same workspace. Use Content-Type: application/json. Unknown JSON fields are rejected.

{
  "text": "Thanks for your message!",
  "reply_to": "wamid.inbound-example",
  "preview_url": false
}

Successful response

200 OK means WhatsApp accepted the message. Save receipt.messages[0].id to match later delivery and read receipts.

{
  "outcome": "accepted",
  "receipt": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "user:50972923564215",
        "wa_id": "user:50972923564215"
      }
    ],
    "messages": [{"id": "wamid.outbound-example"}]
  }
}

Accepted does not mean delivered or read. Those receipts arrive through your webhook.

Use both the HTTP status and outcome to decide what to do next. API errors have this shape:

{
  "error": {"code": "recipient_not_known"},
  "outcome": "not_sent"
}

Routing errors, such as an unsupported path or method, may return plain text instead of this JSON error format.

Unpoll sends an HTTPS POST to your configured endpoint with Content-Type: application/json. Each whatsapp.updates event contains a batch of incoming messages, delivery/read receipts, or both.

{
  "schema_version": 1,
  "event_id": "0194d893-15d0-4a5d-9298-f36c98b8844a",
  "agent_id": "5a302db8-dc32-48f2-9319-0b2f38c2b8ac",
  "type": "whatsapp.updates",
  "data": {
    "object": "whatsapp_agent_platform",
    "entry": [{
      "id": "123456789",
      "changes": [{
        "field": "messages",
        "value": {
          "messaging_product": "whatsapp",
          "contacts": [],
          "messages": [{
            "from": "user:50972923564215",
            "id": "wamid.inbound-example",
            "timestamp": "1790726400",
            "type": "text",
            "text": {"body": "Hello!"}
          }],
          "statuses": [{
            "id": "wamid.outbound-example",
            "status": "delivered",
            "recipient_id": "user:50972923564215",
            "timestamp": "1790726401"
          }]
        }
      }]
    }],
    "next_offset": 1287
  }
}

Processing messages and receipts

Walk data.entry[].changes[].value. Handle messages[] and statuses[] independently: either array can be empty. For a text message, read messages[].text.body and save its id if you want to quote a reply.

Match statuses[].id to your saved outbound message ID. The status is delivered or read. Timestamps are Unix seconds encoded as strings.

Inbound message types also include image, audio, video, document, sticker, and reaction. Check type before reading a text body, and tolerate new fields. The send API currently supports text only; Unpoll has no media download or upload endpoint.

Verify every webhook before parsing its JSON or performing work. Each attempt includes two headers:

Webhook-Timestamp: 1790726400
Webhook-Signature: v1=HMAC_SHA256_HEX_DIGEST

The signature is lowercase hexadecimal HMAC-SHA256 over timestamp + "." + raw_body. Use the exact UTF-8 signing-secret string as the key; do not base64-decode it or reconstruct the JSON.

import hashlib
import hmac
import re
import time


def verify_webhook(secret: str, timestamp: str,
                   signature: str, body: bytes) -> bool:
    if not re.fullmatch(r"[0-9]{1,20}", timestamp):
        return False
    if not re.fullmatch(r"v1=[0-9a-f]{64}", signature):
        return False
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False
    signed = timestamp.encode("ascii") + b"." + body
    digest = hmac.new(
        secret.encode("utf-8"), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest("v1=" + digest, signature)

Pass the raw request bytes and exactly one value for each header. Your HTTP handler must reject missing or duplicate timestamp/signature headers before calling this function. Keep your server clock synchronized; the accepted timestamp window is five minutes in either direction.

Rotating your webhook secret

Saving a webhook configuration generates a new secret, even when the URL stays the same. Already queued events keep their original URL and signing secret. Retain old verification secrets while their deliveries drain; try each retained secret against the same signed bytes.

Webhooks use at-least-once delivery with a bounded retry policy. Duplicate events can arrive, and delivery order is not guaranteed.

1. Verify the signature. Reject requests that fail verification.
2. Accept work durably. Store event_id atomically with your queued work. If it is already accepted, return a 2xx without repeating that work.
3. Acknowledge promptly. Return any 2xx after durable acceptance. Process slower work, such as AI generation, asynchronously. The webhook HTTP timeout is 15 seconds.

On retryable responses, Retry-After accepts seconds or an HTTP date and sets a minimum delay, even above the normal backoff. Invalid values are ignored; a delay above 365 days causes terminal failure.

Delivery stops after 12 claimed attempts unless an attempt succeeds. A worker restart can consume an attempt before a request is sent. Oversized payloads and blocked destinations also fail without sending. Fix the receiver, then use Retry delivery on the agent’s delivery page to restart a failed job. Its event ID, destination, and signing secret stay the same.

Disabling webhook delivery pauses new attempts; polling and event queueing continue. Re-enabling resumes pending delivery. A request already in flight may still arrive.

Agent connection, key management, webhook configuration, and failed-delivery retries are available in the dashboard. Public JSON management, media, typing-indicator, and mark-as-read endpoints are not currently available.

The health endpoint returns 200 OK with an empty body when the app is running. It checks process liveness, not database connectivity, polling progress, or webhook delivery.