Create New Session

Active Sessions

This session will be used for all actions below

Enter with country code

Current Status:

💡 Use "List Chats" action first to load available chats

💡 Use "List Chats" action first to load available chats

Leave empty to screenshot main screen, or select a chat

Screenshot Preview

Screenshot

Configure storage and webhooks for this session

Configure your Appwrite instance connection. These credentials are required for all Appwrite features.

Appwrite Storage Resources

Specify the database, collection, and bucket IDs for message storage.

ℹī¸ Auto-Creation

If the database, collection, or bucket don't exist in your Appwrite instance, they will be created automatically when you send your first message.

Send webhook events to external URLs (like your own server, n8n, Zapier, etc.)

Media URLs Will Not Be Sent

Local message storage is currently disabled. Enable "Save to Local Database" above to include temporary media download URLs (valid for 1 hour) in webhook payloads.

Enter the full URL where you want to receive webhook events (e.g., webhook.site, n8n, your own server)

Active Webhooks

No external webhooks configured

Message History

Chats

Note: Messages and media files are stored locally in the /data directory when local storage is enabled in webhook configuration.

Select Session

Automation API Key

⚠ī¸ This API key is different from your main API key. Use it exclusively for automation API calls.

Need a new key?

Target Database & Collection

ℹī¸ Appwrite connection (endpoint/project/API key) is automatically used from session configuration. Only specify target database/collection here.

Define which attributes to update and their new values (JSON format)

Example 1: Update single field

{"status": "activated"}

Example 2: Update multiple fields

{"status": "completed", "verified": true, "score": 95}

Example 3: Using dynamic timestamps

{"last_contact": "{{now}}", "contact_date": "{{date}}"}

Example 4: Complex update

{"status": "active", "last_message": "{{date}}", "response_count": 1, "priority": "high"}

Template Variables:

  • {{"{{"}}now{{"}}"}} - Current timestamp (ISO 8601 format)
  • {{"{{"}}date{{"}}"}} - Current date (YYYY-MM-DD format)

Tip: Use {"{"}"{"now"}"{"}"} for current timestamp, {"{"}"{"date"}"{"}"} for current date

Confirmation Message (Optional)

Send an automatic confirmation message to the user who triggered the automation

How many seconds to wait before sending the confirmation message (0 = instant)

Active Automations

Disabled Automations ()

Automation History

Automation Trigger Number Trigger Message Documents Updated Executed At

No automations created yet. Create your first automation above!

API Documentation

Open Swagger

Swagger API Documentation

Enable or disable the Swagger UI endpoint

Setting saved. Restart the server to apply changes.

Base URL

Authentication

Include your API key in request headers:

x-api-key: YOUR_API_KEY

Step 1: Set up Authentication

  • Auth Type: Generic Credential Type
  • Generic Auth Type: Header Auth
  • Name: x-api-key
  • Value: Your API key from this dashboard

Step 2: Configure the Request

  • Method: POST
  • URL:
  • ⚠ī¸ Important: Use the FULL URL including /api/send/text, not just /api
  • Send Body: Yes (JSON)
  • Body Content Type: JSON

Step 3: Add Request Body

{
  "sessionId": "session_123",
  "chatId": "201234567890@c.us",
  "text": "Hello from n8n!"
}

💡 Tip: Replace session_123 with your actual session ID from the Sessions tab

API Endpoints

POST /api/sessions

Create and start a new WhatsApp session

Request Body:

{ "name": "My Session" }

Response:

{ "success": true, "session": { "id": "session_123", "name": "My Session", "status": "INITIALIZING" } }
GET /api/sessions

List all active sessions

Response:

{ "sessions": [{ "id": "session_123", "name": "My Session", "status": "CONNECTED" }] }
GET /api/sessions/:id

Get detailed information about a specific session

Response:

{ "id": "session_123", "name": "My Session", "status": "CONNECTED", "phone_number": "+201234567890" }
DELETE /api/sessions/:id

Delete a session and its data

Response:

{ "success": true }
POST /api/sessions/:id/logout

Logout a session without deleting it

Response:

{ "success": true, "message": "Session logged out" }
POST /api/sessions/:id/regenerate-automation-key

⚠ī¸ Generate a new automation API key for the session (invalidates previous key)

Warning: This will immediately invalidate the previous automation API key. Any external systems using the old key will stop working.

Response:

{ "success": true, "automation_api_key": "auto_abc123..." }
GET /api/sessions/:id/qr

Get QR code for session authentication

Response:

{ "qr_code": "data:image/png;base64,..." }
POST /api/send/text

Send a text message

Request Body:

{ "sessionId": "session_123", "chatId": "201234567890@c.us", "text": "Hello!" }

Response:

{ "success": true, "messageId": "msg_id_123" }
POST /api/send/media

Send image, video, or document

Request Body:

{ "sessionId": "session_123", "chatId": "201234567890@c.us", "mediaUrl": "https://example.com/image.jpg", "caption": "Check this out!" }

Response:

{ "success": true, "messageId": "msg_id_123" }
POST /api/send/voice

Send a voice message

Request Body:

{ "sessionId": "session_123", "chatId": "201234567890@c.us", "voiceUrl": "https://example.com/voice.ogg" }

Response:

{ "success": true, "messageId": "msg_id_123" }
POST /api/send/poll

Send a poll message

Request Body:

{ "sessionId": "session_123", "chatId": "201234567890@c.us", "pollName": "How are you?", "options": ["Great", "Good", "Not bad"], "allowMultipleAnswers": false }

Response:

{ "success": true, "messageId": "msg_id_123" }
POST /api/send/link

Send a link with preview

Request Body:

{ "sessionId": "session_123", "chatId": "201234567890@c.us", "url": "https://example.com", "text": "Check this website!" }

Response:

{ "success": true, "messageId": "msg_id_123" }
POST /api/send/reaction

React to a message with emoji

Request Body:

{ "sessionId": "session_123", "messageId": "msg_id_here", "emoji": "👍" }

Response:

{ "success": true }
POST /api/check-number

Check if a number is registered on WhatsApp

Request Body:

{ "sessionId": "session_123", "phoneNumber": "201234567890" }

Response:

{ "registered": true, "phoneNumber": "201234567890" }
POST /api/sessions/:id/presence

Set presence status (online/offline)

Request Body:

{ "presence": "available" }

Values: "available" or "unavailable"

Response:

{ "success": true, "presence": "available" }
GET /api/sessions/:id/chats

Get all chats for a session

Response:

{ "chats": [{ "id": "201234567890@c.us", "name": "John Doe", "isGroup": false, "unreadCount": 0 }] }
GET /api/sessions/:id/chats/:chatId/messages?limit=50

Get messages from a specific chat

Response:

{ "messages": [{ "id": "msg_123", "body": "Hello!", "from": "201234567890@c.us", "timestamp": 1234567890 }] }
GET /api/sessions/:id/contacts/:contactId

Get contact information

Response:

{ "id": "201234567890@c.us", "name": "John Doe", "number": "201234567890", "isMyContact": true }
POST /api/webhooks

Create a new webhook

Request Body:

{ "sessionId": "session_123", "url": "https://your-server.com/webhook", "events": ["message"] }

Response:

{ "success": true, "webhookId": 1 }
GET /api/webhooks

List all webhooks

Response:

{ "webhooks": [{ "id": 1, "session_id": "session_123", "url": "https://your-server.com/webhook" }] }
DELETE /api/webhooks/:id

Delete a webhook

Response:

{ "success": true }
GET /api/webhook-config/:sessionId

Get webhook configuration for a session

Response:

{ "session_id": "session_123", "save_to_appwrite": 1, "save_to_local": 1, "appwrite_enabled": 1, "events": ["message"] }
PUT /api/webhook-config/:sessionId

Update webhook configuration

Request Body:

{ "save_to_appwrite": 1, "save_to_local": 1, "appwrite_enabled": 1, "events": ["message", "message_reaction"] }

Response:

{ "success": true }
GET /api/messages?limit=100&offset=0

Get local messages from database

Response:

{ "messages": [{ "id": 1, "from_number": "201234567890", "body": "Hello!", "timestamp": 1234567890 }] }

⚠ī¸ Important: Automation API Uses Different Authentication

Automation endpoints use a per-session automation API key (NOT your main API key).

Include the automation API key in the x-automation-api-key header.

Get your automation API key from the Automations tab in the dashboard after selecting a session.

GET /automations

Get all automations for the authenticated session

Header: x-automation-api-key: your_automation_api_key
# Response [ { "id": 1, "session_id": "session_123", "name": "Auto-activate users", "trigger_numbers": ["201234567890", "966512345678"], "trigger_messages": ["activate", "start"], "appwrite_endpoint": "https://cloud.appwrite.io/v1", "appwrite_project_id": "project_id", "appwrite_database_id": "database_id", "appwrite_collection_id": "collection_id", "document_ids": ["doc_1", "doc_2"], "attribute_updates": {"status": "active", "timestamp": "{{now}}"}, "max_executions": -1, "executions_count": 5, "enabled": 1, "created_at": "2024-01-15T10:00:00.000Z" } ]
POST /automations

Create a new automation (session determined by API key)

Header: x-automation-api-key: your_automation_api_key
Note: Appwrite credentials (endpoint/project/API key) are automatically pulled from the session's Configuration tab. Only specify target database/collection/documents.
# Request Body (session_id and Appwrite connection from API key) { "name": "Auto-activate users", "trigger_numbers": ["201234567890"], // or ["*"] for any number "trigger_messages": ["activate"], // or ["*"] for any message "appwrite_database_id": "database_id", "appwrite_collection_id": "collection_id", "document_ids": ["doc_1"], // or ["*"] for all documents "attribute_updates": { "status": "active", "timestamp": "{{now}}", // Use {{now}} or {{date}} for dynamic values "last_contact": "{{date}}" }, "max_executions": -1, // -1 for infinite, or any positive number "send_confirmation": true, // Optional: Send message to trigger user "confirmation_message": "Your request has been processed!", // Message text "confirmation_delay": 5 // Delay in seconds (0 = instant) } # Response { "success": true, "id": 1 }
PUT /automation/:id

Update an existing automation

# Request Body (same as create) { "session_id": "session_123", "name": "Updated automation name", "trigger_numbers": ["201234567890"], "trigger_messages": ["activate"], "enabled": false, // Set to false to disable ... } # Response { "success": true }
DELETE /automation/:id

Delete an automation and its history

# Response { "success": true }
GET /automation-history

Get automation execution history (session determined by API key)

Header: x-automation-api-key: your_automation_api_key
# Response [ { "id": 1, "automation_id": 1, "automation_name": "Auto-activate users", "session_id": "session_123", "trigger_number": "201234567890", "trigger_message": "activate", "documents_updated": ["doc_1", "doc_2"], "executed_at": "2024-01-15T10:30:00.000Z" } ]

⚠ī¸ Important: This API Sends Events via POST

This WhatsApp API sends webhook events to your URL using POST requests. It does NOT provide a GET endpoint to fetch events. Your webhook receiver must accept incoming POST requests.

❌ This will NOT work: Polling the webhook URL with GET requests to fetch events

✅ This will work: A server endpoint that receives POST requests from this API

How External Webhooks Work:

  1. Create a webhook in the Webhooks tab with your URL (e.g., https://yourdomain.com/webhook)
  2. Copy the webhook's API key using the 🔑 button
  3. When a WhatsApp event occurs (message received, etc.), this API will send a POST request to your URL
  4. Your server receives the POST request with the event data in the body
  5. The webhook API key is sent in the X-Webhook-Key header for verification

Example: n8n Webhook Setup

  1. In n8n, add a Webhook node
  2. Set HTTP Method to POST
  3. Copy the webhook URL from n8n (e.g., https://your-n8n.com/webhook/abc123)
  4. Paste this URL in the Webhooks tab and create the webhook
  5. (Optional) Add authentication in n8n to verify the X-Webhook-Key header

Example Webhook POST Request:

When a message is received, this API sends:

POST https://yourdomain.com/webhook
Headers:
  Content-Type: application/json
  X-Webhook-Key: whk_47b80ad07c0a03e6d4576e53d202b947...

Body:
{
  "event": "message",
  "sessionId": "session_123",
  "from": "201234567890@c.us",
  "body": "Hello!",
  "timestamp": 1234567890,
  "hasMedia": false
}

Simple Node.js Webhook Receiver Example:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const apiKey = req.headers['x-webhook-key'];
  const event = req.body;

  console.log('Received webhook:', event);
  console.log('API Key:', apiKey);

  // Process the event here
  // Store in database, trigger actions, etc.

  res.json({ success: true });
});

app.listen(3000);

How to Display Events in a Web Application:

Since this API pushes events using POST requests (not GET polling), to display events in a web application you need:

  • A backend server that receives POST webhooks from this API
  • Store events in a database or message queue
  • Your frontend app can then fetch events from your backend using GET requests
  • Alternatively, use WebSockets to push events to your frontend in real-time

💡 Tip: For testing webhooks locally, use tools like ngrok or webhook.site to create a public URL that forwards to your local server.

Phone Number Format

Always use the format: COUNTRYCODE+NUMBER@c.us (without the + symbol)

Examples:

  • Egypt: 201234567890@c.us
  • Saudi: 966512345678@c.us
  • USA: 11234567890@c.us