Troubleshooting

Missing key: add `x-api-key: $HOOKMESSAGE_API_KEY` to the backend request.

Invalid key: rotate the API client, copy the new `was_...` key once, update backend secrets, and redeploy.

Wrong role: use a `send_message` key for `/api/messages/send` and an `otp` key for `/api/otp/send`.

Sender list empty: assign the connected sender in Dashboard > API Keys > selected client > Assign senders.

Wrong sender assignment: call `GET /api/senders`; only send with sender IDs returned by that key.

Sender not connected: open Dashboard > WhatsApp Numbers and scan a fresh QR.

Disconnected sender: wait for reconnect, then confirm `/api/senders/{sender_id}/status` returns `connected`.

Invalid phone: include country code and avoid local leading zero, for example `212612345678`.

Blocked or unsubscribed recipient: unblock or reactivate the contact before sending.

Stuck queued: check worker health, sender status, daily sender limit, monthly quota, and webhook/status logs.

Quota exhausted: open Dashboard > Billing & Plans, upgrade or wait for the billing reset, then retry safely with idempotency.

OpenAPI not loading: set frontend `BACKEND_BASE_URL` to the backend API origin and verify the backend serves `/openapi.yaml`.

Webhook signature invalid: verify the exact raw request body with the current signing secret and `x-wa-timestamp`.

No webhook delivery: confirm the endpoint is active, public HTTPS is reachable, event types match, and the tunnel is running in local dev.

SDK timeout or network failure: confirm `HOOKMESSAGE_BASE_URL`, increase SDK timeout if needed, and retry temporary 429/5xx failures with the same `idempotency_key`.