📱 WhatsApp API — Integration Guide

1. Overview & Authentication

This API lets you manage WhatsApp instances and send/receive messages programmatically. There are two authentication keys you'll use:

Base URL:

2. Quick Start

Here's the typical flow to get a WhatsApp instance running:

1. Create an instance → you receive an instance token
2. Get the QR code → display it to the user
3. User scans QR with their WhatsApp → instance becomes connected
4. Send messages using the instance token
5. Receive messages via webhooks

3. Create Instance

POST /api/instance/{instanceId}/init

Creates a new WhatsApp instance. Uses your API Key.

Copycurl -X POST {BASE_URL}/api/instance/my_clinic_wa/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "dr_smith"
  }'

Response:

{
  "success": true,
  "message": "Instance created successfully",
  "instanceId": "my_clinic_wa",
  "userId": "dr_smith",
  "token": "a1b2c3d4e5f6789...your_instance_token"
}

4. Get QR Code

GET /api/instance/{instanceId}/qr?format=base64

Retrieves the QR code image for the user to scan with WhatsApp. Uses Instance Token.

Copycurl "{BASE_URL}/api/instance/my_clinic_wa/qr?format=base64&token=YOUR_INSTANCE_TOKEN"

Response:

{
  "success": true,
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "status": "qr_ready",
  "format": "base64"
}

Formats: base64 (PNG as data URL), svg, terminal, raw

5. Check Instance Status

GET /api/instance/{instanceId}/status

Copycurl -H "Authorization: Bearer YOUR_INSTANCE_TOKEN" \
  "{BASE_URL}/api/instance/my_clinic_wa/status"

Response:

{
  "success": true,
  "instanceId": "my_clinic_wa",
  "status": "connected",
  "userInfo": {
    "name": "Dr Smith Clinic",
    "number": "60123456789"
  }
}

6. Send Text Message

POST /api/instance/{instanceId}/messages/send

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/messages/send?token=YOUR_INSTANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "60123456789",
    "type": "text",
    "message": "Hi! Your appointment is confirmed for tomorrow at 10am."
  }'

Response:

{
  "success": true,
  "messageId": "3EB01A2B3C4D5E6F",
  "timestamp": "2026-03-23T10:30:00.000Z",
  "to": "60123456789",
  "type": "text"
}

7. Send Media

Image

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/messages/send?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "60123456789",
    "type": "image",
    "image": {
      "url": "https://example.com/xray-result.jpg",
      "caption": "Your X-ray results"
    }
  }'

Document

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/messages/send?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "60123456789",
    "type": "document",
    "document": {
      "url": "https://example.com/invoice.pdf",
      "filename": "Invoice_March_2026.pdf",
      "mimetype": "application/pdf"
    }
  }'

Supported types: text, image, video, audio, document

Media can be sent via url (public URL) or data (base64 encoded).

8. Groups

List Groups

GET /api/instance/{instanceId}/groups?token=YOUR_TOKEN

Send to Group

POST /api/instance/{instanceId}/groups/messages/send

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/groups/messages/send?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "120363025246125789@g.us",
    "type": "text",
    "message": "Reminder: Staff meeting at 3pm today"
  }'

9. Webhooks (Receive Messages)

Register a webhook URL to receive real-time notifications when messages arrive or connection status changes.

Register Webhook

POST /api/instance/{instanceId}/webhook

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/webhook?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/api/whatsapp-webhook",
    "events": ["message", "message_ack", "connection_update"]
  }'

Webhook Payload (incoming message)

When a message is received, your webhook URL gets a POST request like:

{
  "event": "message",
  "instanceId": "my_clinic_wa",
  "data": {
    "from": "60123456789",
    "fromName": "Patient John",
    "message": "Hi, I'd like to book an appointment",
    "messageType": "text",
    "timestamp": 1711180200,
    "messageId": "3EB0..."
  }
}

10. Disconnect / Delete Instance

Disconnect (Logout)

POST /api/instance/{instanceId}/logout?token=YOUR_TOKEN

Disconnects WhatsApp. The instance and token remain — you can reconnect by scanning a new QR code.

Copycurl -X POST "{BASE_URL}/api/instance/my_clinic_wa/logout?token=YOUR_TOKEN"

Delete Instance (Permanent)

DELETE /api/instance/{instanceId}?token=YOUR_TOKEN

Permanently removes the instance, its data, and token. Cannot be undone.

Copycurl -X DELETE "{BASE_URL}/api/instance/my_clinic_wa?token=YOUR_TOKEN"

11. List All Your Instances

GET /api/instances

Uses your API Key (not instance token). Returns all instances you've created.

Copycurl -H "Authorization: Bearer YOUR_API_KEY" "{BASE_URL}/api/instances"

12. Error Handling

All error responses follow this format:

{
  "success": false,
  "error": "Description of what went wrong"
}