Getting Started

Quickstart

Create a workspace, generate an API key, connect a sender, and queue your first WhatsApp message.

1. Create a workspace

A workspace owns senders, API keys, contacts, message history, billing, team members, and security settings.

Keep testing in a sandbox or low-volume plan until your sender is connected, your API key is stored server-side, and your application handles failed messages correctly.

2. Create an API key

Open Dashboard, go to API Keys, create a client, choose the role that matches the integration, and assign the sender IDs it can use.

The key is shown only when created or rotated. Store it in your backend environment, not in browser JavaScript, mobile apps, or public repositories.

3. Connect a sender

Create a sender from the dashboard, scan the QR code, and wait until the sender status becomes connected.

Messages can only be sent through connected senders assigned to the API key. This protects workspace isolation and prevents one integration from using another workspace number.

4. Send a message

Use a server-side request with `content-type: application/json` and `x-api-key`. The API validates the key, verifies sender access, checks limits, stores a message record, and queues delivery.

Test with cURL first. After the cURL request returns `queued`, move the same base URL, key, sender ID, and idempotency pattern into the SDK or your framework service.

POST/api/messages/send

Queue a customer message through a connected sender.

Parameter	Type	Description
`x-api-key`required	header	API key created in the dashboard.
`sender_id`	uuid	Connected sender assigned to the API key. Omit only for a key configured with random platform sender mode.
`receiver_number`required	string	Destination phone number in international format.
`message`	string	Message body. Required unless `attachment` is provided.
`idempotency_key`	string	Optional duplicate protection key, max 160 characters.

curl

bash

curl -X POST "$HOOKMESSAGE_BASE_URL/api/messages/send" \
  -H "content-type: application/json" \
  -H "x-api-key: $HOOKMESSAGE_API_KEY" \
  -d '{
    "sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
    "receiver_number": "212612345678",
    "message": "Your order is confirmed.",
    "source_system": "checkout",
    "source_reference": "order_1042"
  }'

201 response

json

{
  "message_id": "2b7a0bd5-1a0d-4e6c-85b1-a7f44f92dfb0",
  "workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
  "status": "queued",
  "duplicate": false
}

5. Diagnose first-send errors

If the first send does not queue, use the error code and the sender status before changing application code.

Most setup failures are caused by a wrong base URL, missing API key header, unassigned sender, disconnected sender, local-format phone number, blocked receiver, or exhausted quota.

Need help?

Use Book Integration Help if you want setup help for OTP or automated customer messaging.

Next steps

Authentication and access

HookMessage separates customer API keys, dashboard sessions, and internal platform access.

Workspaces

A workspace is the tenant boundary for every customer resource.

Senders and sessions

A sender is the WhatsApp number used to deliver messages for a workspace.

Send customer messages

Use `/api/messages/send` for opted-in, application-triggered customer communication.