Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openagen/zeroclaw/llms.txt

Use this file to discover all available pages before exploring further.

The ZeroClaw gateway is a lightweight HTTP server that accepts inbound webhooks, issues bearer tokens to paired clients, and routes Meta WhatsApp events to the agent. By default it binds to 127.0.0.1:42617 and refuses public-interface binding unless a tunnel is active or allow_public_bind = true is set in config.toml. Start the gateway directly or as part of the full daemon: 
zeroclaw gateway           # gateway only
zeroclaw daemon            # gateway + channels + scheduler

​
Authentication model

All requests except GET /health and GET /whatsapp require a bearer token. Obtain one by exchanging the 6-digit pairing code printed on gateway startup via POST /pair. 
Authorization: Bearer <token>

​
Endpoints

​
GET /health

Public health check. Returns a 200 OK with a JSON body indicating gateway status. No credentials required and no sensitive information is returned.
​
header.Authorization
string
Not required for this endpoint.
​
status
string
required
Gateway status string, for example "ok".
curl http://127.0.0.1:42617/health

​
POST /pair

Exchanges the one-time 6-digit pairing code shown on gateway startup for a long-lived bearer token. The pairing code is valid for a single use.
​
header.X-Pairing-Code
string
required
The 6-digit one-time pairing code printed to the terminal when the gateway starts.
​
token
string
required
Bearer token to use in the Authorization header for all subsequent requests.
curl -X POST http://127.0.0.1:42617/pair \
  -H "X-Pairing-Code: 482931"
Each pairing code can only be used once. If the gateway restarts, a new pairing code is generated and any existing bearer tokens issued by the previous session are invalidated.

​
POST /webhook

Sends a message to the agent. The gateway queues the message, runs the agent loop, and returns the response. Supply an idempotency key to prevent duplicate processing when retrying on network failure.
​
header.Authorization
string
required
Bearer <token> obtained from POST /pair.
​
header.X-Idempotency-Key
string
Optional. A unique string (UUID or similar) for this request. Duplicate requests with the same key within the deduplication window are ignored.
​
body.message
string
required
The prompt to send to the agent.
​
response
string
required
The agent’s reply text.
curl -X POST http://127.0.0.1:42617/webhook \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the current system status?"}'

​
GET /whatsapp

Meta webhook verification endpoint. Meta calls this URL with query parameters to confirm your webhook subscription before enabling message delivery. No bearer token is required; verification is performed using the hub.verify_token value configured in config.toml.
​
query.hub.mode
string
required
Meta sets this to "subscribe" for verification requests.
​
query.hub.verify_token
string
required
Token that must match the value configured in your ZeroClaw WhatsApp channel settings.
​
query.hub.challenge
string
required
Random string that ZeroClaw echoes back to Meta to confirm the subscription.
​
(body)
string
required
The raw hub.challenge value echoed as plain text with status 200 OK.
curl "http://127.0.0.1:42617/whatsapp\
?hub.mode=subscribe\
&hub.verify_token=my-verify-token\
&hub.challenge=abc123"
This endpoint is called by Meta’s servers during webhook setup. You do not call it yourself. Ensure the gateway is reachable from the internet via a tunnel (Cloudflare Tunnel, ngrok, Tailscale, or a custom tunnel) when registering the webhook in the Meta Developer portal.

​
POST /whatsapp

Receives incoming WhatsApp messages from Meta. Meta sends a signed JSON payload for each user message. When app_secret is configured, ZeroClaw verifies the X-Hub-Signature-256 header before processing.
​
header.X-Hub-Signature-256
string
HMAC-SHA256 signature of the raw request body, prefixed with sha256=. Required when app_secret is set in your WhatsApp channel configuration. Requests with an invalid signature are rejected with 403 Forbidden.
​
body
object
required
Meta’s standard WhatsApp Business Cloud API event payload. ZeroClaw normalizes both text messages and media events before dispatching them to the agent.
​
(status)
number
required
Returns 200 OK to acknowledge receipt. Meta retries delivery on any non-2xx response.
curl -X POST http://127.0.0.1:42617/whatsapp \
  -H "Content-Type: application/json" \
  -d '{
    "object": "whatsapp_business_account",
    "entry": [{
      "changes": [{
        "value": {
          "messages": [{
            "from": "15551234567",
            "text": {"body": "Hello"},
            "type": "text"
          }]
        }
      }]
    }]
  }'
Configure app_secret in your WhatsApp channel settings for production deployments. Without signature verification, any client that can reach the gateway endpoint can inject messages into the agent.

​
Endpoint summary

MethodPathAuthDescription
GET/healthNoneHealth check
POST/pairX-Pairing-Code headerExchange pairing code for bearer token
POST/webhookAuthorization: BearerSend a message to the agent
GET/whatsappQuery params (Meta)Meta webhook subscription verification
POST/whatsappX-Hub-Signature-256 (Meta)Incoming WhatsApp message delivery

Build docs developers (and LLMs) love

Get started for freeTalk to us