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

Messaging

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

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