API Documentation

Getting Started

Base URL: https://yourdomain.com/api/v1

All API requests require authentication. Use either a Session API Key (Bearer token) for session-scoped endpoints (send-message, contacts, groups) or a Personal Access Token (X-API-Token header) for account-level endpoints (sessions list, status).

Session keys are found on each session's detail page in the dashboard. Personal tokens are created at /dashboard/api-tokens.

Authentication

Session Key (Bearer)

Use for send-message, contacts, groups, and any endpoint that operates on a specific session. Pass as Authorization: Bearer YOUR_SESSION_KEY.

Personal Access Token

Use for listing sessions, creating sessions, and account-level operations. Pass as X-API-Token: YOUR_PAT.

Sessions

• GET /whatsapp-sessions — List all sessions (PAT)
• POST /whatsapp-sessions — Create session (PAT)
• GET /whatsapp-sessions/:id — Get session (Session Key or PAT)
• DELETE /whatsapp-sessions/:id — Delete session
• POST /whatsapp-sessions/:id/connect — Start connection
• POST /whatsapp-sessions/:id/disconnect — Disconnect
• GET /whatsapp-sessions/:id/qrcode — Get QR code (when CONNECTING)

Messages

POST /send-message — Send a message. The type is auto-detected from the payload.

Supported types

text, image, video, audio, document, sticker, location, contact, poll, quoted, viewOnce, mentions

Example: Send text

const res = await fetch("https://yourdomain.com/api/v1/send-message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_SESSION_API_KEY",
  },
  body: JSON.stringify({
    to: "1234567890",
    text: "Hello from the API!",
  }),
});
const data = await res.json();
console.log(data.messageId);

Payload examples

{ "to": "1234567890", "image": { "url": "https://...", "caption": "Optional" } }

{ "to": "1234567890", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "San Francisco" } }

{ "to": "1234567890", "contact": { "fullName": "John Doe", "phoneNumber": "+1234567890" } }

Contacts

• GET /contacts — List contacts
• PUT /contacts — Upsert contact
• GET /contacts/:phone — Get contact
• GET /on-whatsapp/:phone — Check if number is on WhatsApp

Groups

• GET /groups — List groups
• POST /groups — Create group
• GET /groups/:jid — Get group metadata
• GET /groups/:jid/participants — List participants
• POST /groups/:jid/participants/add — Add participants
• POST /groups/:jid/participants/remove — Remove participants
• POST /groups/:jid/leave — Leave group

Webhooks

Configure a webhook URL per session. When events occur (messages, presence, etc.), we POST to your URL.

Payload schema

{
  "event": "message.received",
  "sessionId": "...",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": { ... }
}

Event types

Rate Limits

When rate limited, responses include 429 and Retry-After header.

Error Codes