DEVELOPER REFERENCE · v1

WhatsApp API documentation

Connect a session, make a request, and receive the result. Find the endpoint, fields and example you need.

Your first request

Create a session. Buy one in your workspace, or use an available trial. A purchased session appears after payment is verified. Save its session token when it is shown. Partners buy prepaid session credits in the dashboard, then redeem one with the Manager API to receive a session token.
Start the session. Call POST /api/v1/sessions/{sessionId}/start. Poll GET /api/v1/sessions/{sessionId}/health until the status is SCAN_QR_CODE before requesting pairing data. If it is already WORKING, the session is connected and you can send a request.
Connect WhatsApp. Scan the QR code in your workspace, or request it with the API: GET /api/v1/sessions/{sessionId}/qr, or request a phone-number code with POST /api/v1/sessions/{sessionId}/pair.
Send a request. Replace the placeholders with your token, the session's short ID or UUID and the intended recipient.

Check the connection first with GET /api/v1/sessions/{sessionId}/health.

Each send request is a new message. An accepted send returns 201; delivery and read updates can arrive later by webhook. A timeout may still mean the message was sent.

Send a text message

curl -X POST 'https://wathook.com/api/v1/whatsapp/YOUR_SESSION_ID/messages/text' \
  -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"to":"15555550100","text":"Hello"}'

Choose the right credential

Session token

Send Authorization: Bearer SESSION_TOKEN for one session. It can use only that session's messaging and WhatsApp endpoints. It cannot access another session or list all sessions in your account. The token of a partner's session works the same way.

Partner manager key

For your server only: provision a session from prepaid credit or delete an owned partner session. Buy credits in the dashboard. Use each session's token with /api/v1 for connection and messaging operations.

Base URL https://wathook.comEndpoint paths below include their API prefix.

Endpoint reference

33 endpoints in this area

Session API

Use one session token for one WhatsApp session. Check its live health, connect it, send supported messages and use the retained WhatsApp operations. The token of a partner's session works here the same way.

Sessions

Check live session health

GETSession token

Session token scope. Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.

/api/v1/sessions/{sessionId}/health

Check the WhatsApp service live and return safe session status with local billing metadata. healthy is true only for WORKING.

A session Bearer token can access only its own session.
Reads the WhatsApp service directly. An existing local reservation whose service session does not exist returns HTTP 404; list responses can still show that reservation. Transport/service errors stay errors and never claim health. Other valid session states return healthy:false. Owned expired sessions remain readable; suspended accounts remain denied. Only safe session fields are returned.

Request fields 1

Check live session health request fields
Field	Location / type	Description
`sessionId`Required	pathstring (UUID or short ID)	Your session's UUID or its 5-character short ID (shortId); both name the same session.Example: `11111111-1111-4111-8111-111111111111`

Request example

cURL request

curl --request GET 'https://wathook.com/api/v1/sessions/11111111-1111-4111-8111-111111111111/health' \
  --header 'Authorization: Bearer YOUR_SESSION_TOKEN'

Examples use placeholders. Replace them in your own application before sending a request.

Example response 200

application/json

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "shortId": "k7m2q",
    "name": "Support",
    "status": "WORKING",
    "phoneNumber": "15550001111",
    "billingState": "paid",
    "paidUntil": "2026-11-11T12:00:00.000Z",
    "expiredAt": null,
    "createdAt": "2026-10-11T12:00:00.000Z",
    "lastActivityAt": "2026-10-11T12:00:00.000Z",
    "healthy": true,
    "accountName": "Support team"
  }
}

Illustrative response. Values and IDs depend on your session and the service response.

Read the result

Successful API responses use a data envelope. Errors include error.code, error.message and, where relevant, error.details.

Common API errors
Status	Meaning	Next step
`400`	Invalid or unavailable request	Check the required fields and offered message types.
`401 / 403`	Authentication or access	Check the credential, session scope and account status.
`402`	Payment or session expiry	Check billing and renew the session if needed.
`404`	Resource not found	Check the ID. A live session read also returns the service's 404.
`409 / 429`	Conflict or applicable limit	Read the error details and any Retry-After header.
`503`	Service unavailable	Read the code. A service connect-phase failure means the request did not reach it; preparation or restart errors can also return 503.
`504 / 502`	Timeout or upstream failure	Read the code and `details.mayHaveExecuted`: when it is true, an unanswered send may have completed and a new request can send another copy; when it is false, nothing was sent.

Wathook does not retry outgoing messages automatically or block future sends after a failed request. Every send request is a new message, so repeating one can send another copy.

504 Gateway Timeout example

{
  "error": {
    "code": "SERVICE_TIMEOUT",
    "message": "The WhatsApp service did not answer in time. The operation may have completed.",
    "details": {
      "mayHaveExecuted": true
    }
  }
}

Receive updates

Choose your events

messages.post carries incoming/outgoing messages, statuses.post reports message status and session.patch reports session changes. Subscribe to the families your application uses.

Accept and process

Return a 2xx response promptly. Each source event gets at most one attempt per target, without retries or replay. The service can emit one WhatsApp message again under a new event ID; for repeated messages.post notifications, use the raw part of providerMessageId with fromMe.

Verify the signature

When configured, verify X-Webhook-Signature as HMAC-SHA256 of the timestamp, a dot and the raw request body, using your webhook secret.

Use a public HTTPS receiver. Account targets receive that account's session events; session targets receive only their own session. Separate account and session targets receive separate attempts, even when they use the same URL. Receipts record observed results: a successful HTTP response confirms acceptance, and an unconfirmed result may still have reached the receiver. A process failure before forwarding can lose the event. Overload may prevent a new notification from being admitted. A business notification can instead report NOT_ATTEMPTED_CAPACITY without rolling back the business action; it is not retried.

Webhook event example

{
  "id": "00000000-0000-4000-8000-000000000010",
  "type": "statuses.post",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "session_id": "00000000-0000-4000-8000-000000000001",
  "session_short_id": "k7m2q",
  "data": {
    "sessionId": "00000000-0000-4000-8000-000000000001",
    "providerEvent": "message.ack",
    "providerMessageId": "true_15550001001@c.us_EXAMPLE001",
    "ack": 1,
    "ackName": "SERVER",
    "state": "sent",
    "timestamp": 1767268800000,
    "data": {
      "id": "true_15550001001@c.us_EXAMPLE001",
      "ack": 1,
      "ackName": "SERVER"
    }
  }
}

The body ID identifies the event; X-Webhook-Id identifies a delivery and X-Webhook-Timestamp contains Unix seconds. Account billing events do not belong to a session target. Available subscription names describe accepted filters; actual events depend on WhatsApp activity and available events.

Available event subscriptions

messages.post, messages.put, messages.patch, messages.delete, messages.*, statuses.post, statuses.put, statuses.patch, statuses.delete, statuses.*, chats.post, chats.put, chats.patch, chats.delete, chats.*, contacts.post, contacts.put, contacts.patch, contacts.delete, contacts.*, groups.post, groups.put, groups.patch, groups.delete, groups.*, communities.post, communities.put, communities.patch, communities.delete, communities.*, newsletters.post, newsletters.put, newsletters.patch, newsletters.delete, newsletters.*, stories.post, stories.put, stories.patch, stories.delete, stories.*, presences.post, presences.put, presences.patch, presences.delete, presences.*, labels.post, labels.put, labels.patch, labels.delete, labels.*, session.post, session.put, session.patch, session.delete, session.*, users.post, users.put, users.patch, users.delete, users.*, service.post, service.put, service.patch, service.delete, service.*, stories.views, billing.*, billing.order.paid, billing.order.fulfilled, billing.order.refunded, billing.session.created, billing.session.renewed, billing.session.expiring, billing.session.expired, billing.session.deleted

Plan your integration

Offered messages: text, images, video and documents. Other message types are currently unavailable.
Session ownership: your token accesses only its own session. Use a separate token for each session you integrate.
Sending: requests on one session run one at a time. Media has size and request limits. Check each endpoint's fields and the retained operation contracts.
Free use: free accounts, trials and Sandbox have applicable quotas. Paid sessions and the owner bypass commercial throttles; service limits still apply.
Connection: this integration uses WhatsApp Web. Pairing, account restrictions and protocol changes can affect availability. An accepted send is not a delivery guarantee.