Start here
Choose the correct setup path before you create an API key or connect a WhatsApp number.
Choose your setup
HookMessage has two sender modes. Choose one before following code examples because the request fields are different.
If you are evaluating the API, start with Free Sandbox. If you are preparing live customer traffic, use a paid plan and connect a WhatsApp number that your business controls.
- Free SandboxHookMessage chooses a managed company sender. Do not connect a number and do not send `sender_id`.
- Paid planconnect your own WhatsApp number, assign it to the API key, and send its `sender_id` with each request.
- Automatic platform routingavailable only when an API key is configured for platform sender selection. Omit `sender_id` and HookMessage chooses an eligible platform sender.
Not sure which path to use?
Use Free Sandbox first. You can prove the request, response, and status flow without connecting your own WhatsApp number.
What you need
You need a HookMessage customer account and a backend environment that can make HTTPS requests. Node.js, Next.js server routes, Python, PHP, Laravel, Fastify, and similar server runtimes are supported.
Never put a HookMessage API key in React client components, browser JavaScript, mobile application bundles, or public repositories.
- Accountregister, verify your email, and open the customer dashboard.
- API keycreate an `otp` key for OTP requests or a `send_message` key for custom messages.
- Backend secretsave the one-time `was_...` value as `HOOKMESSAGE_API_KEY`.
- API URLuse `https://api.hookmessage.com` in production.
- Test receiveruse a phone number in international format, for example `212612345678` without `+`, spaces, or a leading local zero.
Your first success
A successful send request returns HTTP 201, a `message_id`, `status: queued`, and `credits_reserved`. Queued means HookMessage accepted the request; it does not yet mean WhatsApp delivered it.
Save the `message_id`, then request its status until it becomes `sent` or `failed`. In production, use signed webhooks instead of frequent polling.
- 201 queuedrequest accepted and waiting for a worker.
- processinga worker is attempting delivery.
- sentthe connected WhatsApp service accepted the message.
- faileddelivery stopped; inspect `error_message` before deciding whether to retry.
Where to go next
Follow the Free Sandbox quickstart for the shortest working request. Use the sender guide only when you are ready to connect your own number.
- Free Sandboxopen `/docs/quickstart`.
- Send OTPopen `/docs/send-otp`.
- Send a custom messageopen `/docs/send-custom-message`.
- Connect your own numberopen `/docs/senders-and-sessions`.
- Fix an erroropen `/docs/troubleshooting` and search for the exact error code.
Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Continue building
Next steps
Free Sandbox quickstart
The shortest beginner path from a verified account to a queued Free Sandbox OTP.
Glossary
Understand workspaces, keys, senders, receivers, queue states, webhooks, and idempotency.
Senders and sessions
A sender is the WhatsApp number used to deliver messages for a workspace.
Troubleshooting
Use this page when a new integration does not send, status stays queued, or webhook verification fails.