Free Sandbox quickstart
Create an API key and send your first OTP without connecting or selecting a WhatsApp number.
1. Confirm Free Sandbox
Register, verify your email, and open the customer dashboard. New workspaces start on Free Sandbox unless another plan was selected.
Free Sandbox uses a managed HookMessage sender. You do not connect a number, choose a sender, or copy a sender ID for this quickstart.
- Dashboard checkthe current plan says Free Sandbox.
- Sender ruleomit `sender_id` from every Free Sandbox request.
- Usage rulesandbox credits are for testing and are not a live-delivery subscription.
- Expected resultthe dashboard opens and the workspace status is active.
2. Create an API key
Open Dashboard > API Keys and create an `otp` API key. Leave sender assignment empty because Free Sandbox routing is controlled by HookMessage.
The key is shown only when created or rotated. Store it in your backend environment, not in browser JavaScript, mobile apps, or public repositories.
- Nameuse a clear name such as `website-login-otp`.
- Rolechoose `otp` for `/api/otp/send`.
- Senderleave it empty for Free Sandbox.
- Secretcopy the one-time `was_...` value into `HOOKMESSAGE_API_KEY`.
- Expected resultthe new key appears as active in Dashboard > API Keys.
3. Add two environment variables
Add the production API URL and your API key to the backend project. Restart your development server after changing environment variables.
HOOKMESSAGE_BASE_URL=https://api.hookmessage.com
HOOKMESSAGE_API_KEY=was_replace_with_your_keyDo not add a sender variable
Free Sandbox requests must not include `HOOKMESSAGE_SENDER_ID` or `sender_id`. HookMessage selects the managed test sender.
4. Send your first OTP
Run this request from a terminal or backend process. Replace the receiver number with your own test number in international format.
The request intentionally has no `sender_id`.
- Expected resultHTTP 201 with `status: queued` and a `message_id`.
- Browser warningnever move this fetch call into a React client component because it would expose the API key.
- Code handlingstore the OTP on your server only if your verification flow needs it; never return it to unrelated browser clients.
/api/otp/sendGenerate and queue a Free Sandbox OTP through a managed HookMessage sender.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | API key created in the dashboard. |
receiver_numberrequired | string | Destination phone number in international format. |
app_name | string | Name shown in the generated verification message. |
ttl_minutes | integer | How long the generated code remains valid.Default: 10 |
curl -X POST "$HOOKMESSAGE_BASE_URL/api/otp/send" \
-H "content-type: application/json" \
-H "x-api-key: $HOOKMESSAGE_API_KEY" \
-d '{
"receiver_number": "212612345678",
"app_name": "My product",
"ttl_minutes": 10
}'{
"message_id": "2b7a0bd5-1a0d-4e6c-85b1-a7f44f92dfb0",
"status": "queued",
"duplicate": false,
"otp_code": "458934",
"expires_in_minutes": 10
}5. Check delivery
Use the returned `message_id` to check whether the queued job was sent or failed.
Polling is useful during setup. For production traffic, register a signed webhook and update your records from delivery events.
- queued or processingwait briefly and check again.
- sentthe sender service accepted the message.
- failedread `error_message`, then follow the troubleshooting guide.
- Expected resultstatus changes from `queued` to `sent` or provides a specific failure reason.
curl "$HOOKMESSAGE_BASE_URL/api/messages/$MESSAGE_ID" \
-H "x-api-key: $HOOKMESSAGE_API_KEY"6. Move beyond Sandbox
Upgrade only when you are ready for live delivery or need your own connected WhatsApp number. After upgrading, connect the number, assign it to the API key, and add `sender_id` to paid-mode requests.
- 401 unauthorizedconfirm the request sends `x-api-key` from the backend.
- 403 wrong rolecreate an `otp` key for OTP or `send_message` key for custom messages.
- 422 receiver erroruse international digits such as `212612345678`, not `0612345678`.
- No active routing rulethe key or workspace is not configured for managed routing; review API key setup or contact support.
- Queued for too longcheck message status and open `/docs/troubleshooting`.
Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Continue building
Next steps
Send OTP
Use OTP for login, signup, order verification, and customer confirmation flows.
Message status and history
Use message IDs to trace status, delivery attempts, timestamps, and failure reasons.
Troubleshooting
Use this page when a new integration does not send, status stays queued, or webhook verification fails.
Senders and sessions
A sender is the WhatsApp number used to deliver messages for a workspace.