API Overview

Base URL: https://api.wahooks.com/api

Authentication

All endpoints (except health check) require authentication via the Authorization header:

Authorization: Bearer wh_your_api_token

Both API tokens (wh_...) and Supabase JWTs are accepted. See API Tokens for details.

Response format

All responses are JSON. Successful responses return the resource directly. Errors return:

{
  "message": "Connection not found",
  "error": "Not Found",
  "statusCode": 404
}

Status codes

Rate limiting

The API uses rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 response.

Connections

Message history & contacts (read)

Message shape (returned by the message endpoints):

{
  "id": "true_111@g.us_ABC",
  "chatId": "111@g.us",
  "timestamp": 1782419739,
  "fromMe": false,
  "senderJid": "918383880642@s.whatsapp.net",
  "senderPushName": "Alice",
  "type": "text",
  "text": "hello",
  "quotedMessageId": null,
  "media": null
}

type is one of text, image, video, audio, document, location, contact. When media is present, media.url is a WAHooks media-proxy URL you fetch with the same Authorization: Bearer header.

Pagination. GET /chats/:chatId/messages returns:

{ "messages": [ /* newest-first */ ], "nextBefore": "MTA0", "historyStartsAt": null }

Pass the returned nextBefore as ?before= to fetch the next (older) page. When nextBefore is null you've reached the end, and historyStartsAt is set to the oldest message's timestamp — use it to distinguish "no messages" from "history doesn't reach further".

Messaging

The send endpoint accepts an optional replyTo field (message ID) to quote a specific message.

Editing is subject to WhatsApp's rules: you can only edit your own messages, within ~15 minutes of sending. Later edits return 400. The send endpoints return the new message's id, which you pass to the edit endpoint.

All send endpoints include human-like presence by default (read receipt, typing indicator, random delay). Pass skipPresence: true in the request body to disable this when handling presence yourself.

Presence

All three accept { "chatId": "..." } in the request body.

Webhooks

API Tokens

Real-time Events

Connect with any WebSocket client. Events arrive as JSON:

{
  "event": "message",
  "connectionId": "c1a2b3c4-...",
  "payload": {
    "from": "1234567890@c.us",
    "body": "Hello"
  },
  "timestamp": "2026-03-27T12:00:00.000Z"
}

When a message includes media (image, video, document, audio), the payload contains hasMedia: true and a media object with a proxied URL you can fetch directly:

{
  "event": "message",
  "connectionId": "c1a2b3c4-...",
  "payload": {
    "from": "1234567890@c.us",
    "body": "Check this photo",
    "hasMedia": true,
    "media": {
      "url": "https://api.wahooks.com/api/connections/c1a2b3c4-.../media/photo.jpeg",
      "mimetype": "image/jpeg"
    }
  },
  "timestamp": "2026-03-27T12:00:00.000Z"
}

The media.url points to the media proxy endpoint (/connections/:id/media/:filename), which streams the file from the internal WAHA worker. The URL requires authentication (same Authorization header as other endpoints).

See the TypeScript SDK or Python SDK for client libraries.

Billing

Programmatic slot management

After completing checkout once (to add a payment method), you can scale slots entirely from code:

# Set to 10 slots — charges prorated difference immediately
curl -X PUT https://api.wahooks.com/api/billing/slots \
  -H "Authorization: Bearer wh_..." \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10}'

Response:

{
  "slots": 10,
  "status": "upgraded",
  "proratedAmount": 2.25,
  "currency": "usd"
}

• status: "upgraded", "downgraded", or "unchanged"
• proratedAmount: the amount charged (positive) or credited (negative) immediately
• Maximum 100 slots per account by default. Contact support for higher limits.
• If payment fails, the request returns 400 and the subscription remains unchanged.

Other