WA-AKG API Documentation

WhatsApp AI Gateway — Complete API Reference

Professional WhatsApp Gateway REST API with 81 routes for complete WhatsApp automation.

🔐 Authentication

All endpoints require one of the following authentication methods:

📋 Common Parameters

📂 Media

[GET] /media/{filename}

Get uploaded media file

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/media/image.jpg" \
  -H "X-API-Key: your-api-key"

📂 Groups

[POST] /groups/{sessionId}/{jid}/leave

Leave a group

Parameters

Responses

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/session-01/[email protected]/leave" \
  -H "X-API-Key: your-api-key"

[GET] /groups/{sessionId}

List all groups

Get all groups associated with the session

Parameters

Responses

Response Example ( 200):

json
[
  {
    "id": "string",
    "subject": "string",
    "desc": "string",
    "owner": "string",
    "size": 0,
    "isCommunity": true,
    "linkedParentJid": "string",
    "participants": [
      {
        "id": "string",
        "admin": "string"
      }
    ]
  }
]

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/session-01" \
  -H "X-API-Key: your-api-key"

[POST] /groups/{sessionId}/create

Create new group

Create a new group with specified participants

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "subject": "VIP Customers",
  "participants": [
    "[email protected]"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "group": {
    "id": "string",
    "subject": "string",
    "desc": "string",
    "owner": "string",
    "size": 0,
    "isCommunity": true,
    "linkedParentJid": "string",
    "participants": [
      {
        "id": "string",
        "admin": "string"
      }
    ]
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/session-01/create" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subject":"VIP Customers","participants":["[email protected]"]}'

[PUT] /groups/{sessionId}/{jid}/subject

Update group subject

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "subject": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string",
  "subject": "string"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/subject" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subject":"string"}'

[PUT] /groups/{jid}/subject

Update group name

Update group subject (max 100 characters, requires admin)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "sessionId": "string",
  "subject": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Group subject updated successfully",
  "subject": "New Subject"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/[email protected]/subject" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","subject":"string"}'

[PUT] /groups/{sessionId}/{jid}/members

Manage group members

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "action": "add",
  "participants": [
    "string"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string",
  "result": [
    {
      "text": "Hello from WA-AKG!"
    }
  ]
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/members" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"action":"add","participants":["string"]}'

[PUT] /groups/{sessionId}/{jid}/invite

Revoke invite code

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string",
  "newInviteCode": "string",
  "inviteUrl": "string"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/invite" \
  -H "X-API-Key: your-api-key"

[GET] /groups/{sessionId}/{jid}/invite

Get invite code

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "inviteCode": "string",
  "inviteUrl": "string"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/session-01/[email protected]/invite" \
  -H "X-API-Key: your-api-key"

[GET] /groups/{sessionId}/{jid}

Get group details

Get detailed group information

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "id": "string",
  "subject": "string",
  "subjectOwner": "string",
  "subjectTime": 0,
  "desc": "string",
  "descOwner": "string",
  "descId": "string",
  "owner": "string"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/session-01/[email protected]" \
  -H "X-API-Key: your-api-key"

[POST] /groups/{jid}/leave

Leave group

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "sessionId": "string"
}

Responses

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/[email protected]/leave" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string"}'

[POST] /groups/{sessionId}/invite/accept

Accept group invite

Join a group using an invite code

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "inviteCode": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string",
  "groupJid": "string"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/session-01/invite/accept" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"inviteCode":"string"}'

[DELETE] /groups/{sessionId}/{jid}/picture

Remove group picture

Parameters

Responses

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/groups/session-01/[email protected]/picture" \
  -H "X-API-Key: your-api-key"

[PUT] /groups/{sessionId}/{jid}/picture

Update group picture

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( multipart/form-data)

Example:

json
{
  "file": "(binary)"
}

Responses

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/picture" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/file.jpg" \
  -F "type=image" \
  -F "caption=Hello"

[PUT] /groups/{sessionId}/{jid}/settings

Update group settings

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "setting": "announcement",
  "value": true
}

Responses

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"setting":"announcement","value":true}'

[PUT] /groups/{sessionId}/{jid}/description

Update group description

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "description": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "description": "string"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/description" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"description":"string"}'

[PUT] /groups/{sessionId}/{jid}/ephemeral

Toggle disappearing messages

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "expiration": 0
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "expiration": 0
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/[email protected]/ephemeral" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"expiration":0}'

📂 Documentation

[GET] /docs

Get Swagger JSON specification

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/docs" \
  -H "X-API-Key: your-api-key"

📂 Chats

[GET] /chats/by-label/{labelId}

Get chats by label ID

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/chats/by-label/label_01" \
  -H "X-API-Key: your-api-key"

📂 Web Authentication

[POST] /auth/register

Register a new user

Register a user via web.

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "password123"
}

Responses

cURL Example

bash
curl -X POST "http://localhost:3000/api/auth/register" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"[email protected]","password":"password123"}'

[GET] /auth/session

Get current web session

Check if the user is authenticated in the web dashboard

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "user": {
    "name": "string",
    "email": "string",
    "image": "string"
  },
  "expires": "string"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/auth/session" \
  -H "X-API-Key: your-api-key"

[GET] /auth/csrf

Get CSRF token

Retrieve CSRF token for form submissions

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "csrfToken": "string"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/auth/csrf" \
  -H "X-API-Key: your-api-key"

📂 Sessions

[GET] /sessions

List all accessible sessions

Get all sessions accessible to the authenticated user (role-based filtering)

Responses

Response Example ( 200):

json
[
  {
    "id": "clx123abc",
    "name": "Marketing Bot",
    "sessionId": "marketing-1",
    "status": "Connected",
    "userId": "string",
    "botConfig": {
      "text": "Hello from WA-AKG!"
    },
    "webhooks": [
      {
        "text": "Hello from WA-AKG!"
      }
    ],
    "_count": {
      "contacts": 0,
      "messages": 0,
      "groups": 0,
      "autoReplies": 0,
      "scheduledMessages": 0
    },
    "createdAt": "2026-01-15T08:00:00.000Z",
    "updatedAt": "2026-01-15T08:00:00.000Z"
  }
]

cURL Example

bash
curl -X GET "http://localhost:3000/api/sessions" \
  -H "X-API-Key: your-api-key"

[POST] /sessions

Create new WhatsApp session

Creates a new WhatsApp session for QR code pairing

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "name": "Marketing Bot",
  "sessionId": "marketing-1"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "id": "clx123abc",
  "name": "Marketing Bot",
  "sessionId": "marketing-1",
  "status": "Connected",
  "userId": "string",
  "botConfig": {
    "text": "Hello from WA-AKG!"
  },
  "webhooks": [
    {
      "text": "Hello from WA-AKG!"
    }
  ],
  "_count": {
    "contacts": 0,
    "messages": 0,
    "groups": 0,
    "autoReplies": 0,
    "scheduledMessages": 0
  },
  "createdAt": "2026-01-15T08:00:00.000Z",
  "updatedAt": "2026-01-15T08:00:00.000Z"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/sessions" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Marketing Bot","sessionId":"marketing-1"}'

[GET] /sessions/{id}/qr

Get QR code for pairing

Retrieve QR code (string and base64 image) for WhatsApp pairing

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "QR code generated",
  "data": {
    "success": true,
    "qr": "2@AbCdEfGhIjKlMnOp...",
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/sessions/sales-01/qr" \
  -H "X-API-Key: your-api-key"

[GET] /sessions/{id}/bot-config

Get bot configuration

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/sessions/abc123/bot-config" \
  -H "X-API-Key: your-api-key"

[POST] /sessions/{id}/bot-config

Update bot configuration

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "enabled": true,
  "botMode": "BLACKLIST",
  "botBlockedJids": [
    "[email protected]"
  ],
  "autoReplyMode": "SPECIFIC",
  "autoReplyAllowedJids": [
    "[email protected]"
  ],
  "botName": "My Assistant",
  "enableSticker": true
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "id": "string",
  "sessionId": "string",
  "enabled": true,
  "botMode": "string",
  "botAllowedJids": [
    "string"
  ],
  "autoReplyMode": "string",
  "autoReplyAllowedJids": [
    "string"
  ],
  "botName": "string",
  "enableSticker": true,
  "enableVideoSticker": true,
  "maxStickerDuration": 0,
  "enablePing": true,
  "enableUptime": true,
  "removeBgApiKey": "string",
  "createdAt": "2026-01-15T08:00:00.000Z",
  "updatedAt": "2026-01-15T08:00:00.000Z"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/sessions/abc123/bot-config" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"botMode":"BLACKLIST","botBlockedJids":["[email protected]"],"autoReplyMode":"SPECIFIC","autoReplyAllowedJids":["[email protected]"],"botName":"My Assistant","enableSticker":true}'

[GET] /sessions/{id}

Get session details

Get detailed information about a specific session including uptime and status

Parameters

Responses

Response Example ( 200):

json
{
  "id": "clx123abc",
  "name": "Marketing Bot",
  "sessionId": "marketing-1",
  "status": "Connected",
  "userId": "string",
  "botConfig": {
    "text": "Hello from WA-AKG!"
  },
  "webhooks": [
    {
      "text": "Hello from WA-AKG!"
    }
  ],
  "_count": {
    "contacts": 0,
    "messages": 0,
    "groups": 0,
    "autoReplies": 0,
    "scheduledMessages": 0
  },
  "createdAt": "2026-01-15T08:00:00.000Z",
  "updatedAt": "2026-01-15T08:00:00.000Z",
  "uptime": 0,
  "messageCount": 0,
  "hasInstance": true,
  "me": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/sessions/abc123" \
  -H "X-API-Key: your-api-key"

[POST] /sessions/{id}/{action}

Perform session action

Start, stop, restart, or logout a session

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/sessions/abc123/start" \
  -H "X-API-Key: your-api-key"

[PATCH] /sessions/{id}/settings

Update session settings

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "config": {
    "readReceipts": true,
    "rejectCalls": true
  }
}

Responses

cURL Example

bash
curl -X PATCH "http://localhost:3000/api/sessions/abc123/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"config":{"readReceipts":true,"rejectCalls":true}}'

[DELETE] /sessions/{id}/settings

Delete session and logout

Permanently deletes session and logs out from WhatsApp

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/sessions/abc123/settings" \
  -H "X-API-Key: your-api-key"

📂 Session Access

[GET] /sessions/{sessionId}/access

List users with shared access

Get all users who have been granted access to the specified session. Only the session owner or SUPERADMIN can use this endpoint.

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Access list retrieved successfully",
  "data": [
    {
      "id": "string",
      "sessionId": "string",
      "userId": "string",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "user": {
        "id": "string",
        "name": "string",
        "email": "string",
        "role": "string"
      }
    }
  ]
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/sessions/marketing-1/access" \
  -H "X-API-Key: your-api-key"

[POST] /sessions/{sessionId}/access

Grant access to another user

Grant session access to another registered user by email. Only the session owner or SUPERADMIN can use this endpoint. Cannot grant access to the session owner or SUPERADMINs.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "email": "[email protected]"
}

Responses

cURL Example

bash
curl -X POST "http://localhost:3000/api/sessions/marketing-1/access" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

[DELETE] /sessions/{sessionId}/access

Revoke user access

Remove shared access for a user from the specified session. Only the session owner or SUPERADMIN can use this endpoint.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "userId": "clx456ghi"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/sessions/marketing-1/access" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"userId":"clx456ghi"}'

📂 Messaging

[POST] /messages/{sessionId}/{jid}/send

Send message (text/media/sticker)

Universal endpoint for sending text, images, videos, documents, and stickers. Supports mentions and all WhatsApp message types.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "message": {
    "text": "Hello from WA-AKG!"
  },
  "mentions": [
    "[email protected]"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Message sent successfully",
  "data": {
    "key": {
      "remoteJid": "[email protected]",
      "fromMe": true,
      "id": "3EB01234567890"
    },
    "message": {
      "conversation": "Hello from WA-AKG!"
    },
    "messageTimestamp": "1678901234"
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/sales-01/[email protected]/send" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":{"text":"Hello from WA-AKG!"},"mentions":["[email protected]"]}'

[POST] /messages/{sessionId}/{jid}/media

Send media (image/video/audio/document)

Send file using multipart/form-data

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( multipart/form-data)

Example:

json
{
  "file": "(binary)",
  "type": "image",
  "caption": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/media" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/file.jpg" \
  -F "type=image" \
  -F "caption=Hello"

[POST] /messages/{sessionId}/broadcast

Broadcast message to multiple recipients

Send same message to multiple contacts with anti-ban delays (10-20s random)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "recipients": [
    "[email protected]",
    "[email protected]"
  ],
  "message": "Flash Sale! 50% off",
  "delay": 0
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Broadcast started in background"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/broadcast" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"recipients":["[email protected]","[email protected]"],"message":"Flash Sale! 50% off","delay":0}'

[POST] /messages/{sessionId}/{jid}/poll

Send poll message

Create interactive poll (2-12 options, single or multiple choice)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "question": "What's your favorite product?",
  "options": [
    "Product A",
    "Product B",
    "Product C"
  ],
  "selectableCount": 1
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/poll" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"question":"What's your favorite product?","options":["Product A","Product B","Product C"],"selectableCount":1}'

[POST] /messages/{sessionId}/{jid}/location

Send location

Share GPS coordinates with optional name and address

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "latitude": -6.2088,
  "longitude": 106.8456,
  "name": "Central Park",
  "address": "Jakarta, Indonesia"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/location" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"latitude":-6.2088,"longitude":106.8456,"name":"Central Park","address":"Jakarta, Indonesia"}'

[POST] /messages/{sessionId}/{jid}/contact

Send contact card

Share one or multiple contact vCards

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "contacts": [
    {
      "displayName": "John Doe",
      "vcard": "BEGIN:VCARD..."
    }
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/contact" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"contacts":[{"displayName":"John Doe","vcard":"BEGIN:VCARD..."}]}'

[GET] /messages/{sessionId}/download/{messageId}/media

Download message media

Download media from a message (direct binary or redirect)

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/messages/session-01/download/MSG_ID_123/media" \
  -H "X-API-Key: your-api-key"

[POST] /messages/{sessionId}/{jid}/{messageId}/react

React to message with emoji

Add emoji reaction to a message (empty string removes reaction)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "emoji": "👍"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/MSG_ID_123/react" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"emoji":"👍"}'

[POST] /messages/{sessionId}/{jid}/{messageId}/reply

Reply to a message (quoted reply)

Send a quoted reply to a specific message by its ID. Uses same request format as /send — pass a Baileys message object.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "message": {
    "text": "Thanks for your message!"
  },
  "mentions": [
    "[email protected]"
  ],
  "fromMe": true
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Message sent successfully"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/sales-01/[email protected]/3EB0ABCD1234567890/reply" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":{"text":"Thanks for your message!"},"mentions":["[email protected]"],"fromMe":true}'

[POST] /messages/{sessionId}/{jid}/reply

Reply to a message (body-based)

Send a quoted reply with messageId provided in the request body. Same request format as /send with added messageId.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "messageId": "3EB0ABCD1234567890",
  "message": {
    "text": "Sure, let me check that for you!"
  }
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/sales-01/[email protected]/reply" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"messageId":"3EB0ABCD1234567890","message":{"text":"Sure, let me check that for you!"}}'

[POST] /messages/{sessionId}/{jid}/{messageId}/star

Star or unstar a message

Mark a message as starred (saved) or remove the star. Starred messages appear in the Starred Messages section.

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "star": true,
  "fromMe": false
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Message starred"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/MSG_ID_123/star" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"star":true,"fromMe":false}'

[GET] /messages/{sessionId}/search

Search messages

Search messages stored in the database for a session. Supports full-text search, filtering by JID, type, and sender.

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "data": [
    {
      "id": "string",
      "remoteJid": "string",
      "fromMe": true,
      "keyId": "string",
      "pushName": "string",
      "type": "string",
      "content": "string",
      "status": "string",
      "timestamp": "2026-01-15T08:00:00.000Z",
      "quoteId": "string"
    }
  ],
  "pagination": {
    "total": 0,
    "page": 0,
    "limit": 0,
    "pages": 0
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/messages/sales-01/search?q=invoice&[email protected]&type=value&fromMe=value&page=value&limit=value" \
  -H "X-API-Key: your-api-key"

[POST] /messages/{sessionId}/{jid}/list

Send list message

Send a formatted numbered list message

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "title": "Our Services",
  "options": [
    "Web Dev",
    "App Dev",
    "UI/UX"
  ],
  "footer": "Choose one"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/list" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Our Services","options":["Web Dev","App Dev","UI/UX"],"footer":"Choose one"}'

[POST] /messages/{sessionId}/{jid}/spam

Message bombing (Spam)

Send a message multiple times in a row in the background

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "message": "Check our new catalog!",
  "count": 5,
  "delay": 1000
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/spam" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Check our new catalog!","count":5,"delay":1000}'

[POST] /messages/{sessionId}/{jid}/sticker

Send sticker

Convert an image to sticker and send it

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( multipart/form-data)

Example:

json
{
  "file": "(binary)",
  "pack": "string",
  "author": "string",
  "type": "full",
  "quality": 0
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/sticker" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/file.jpg" \
  -F "type=image" \
  -F "caption=Hello"

[POST] /messages/{sessionId}/forward

Forward message

Forward a message to one or multiple chats

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "fromJid": "[email protected]",
  "messageId": "3EB0ABCD1234567890",
  "toJids": [
    "[email protected]"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "string"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/forward" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"fromJid":"[email protected]","messageId":"3EB0ABCD1234567890","toJids":["[email protected]"]}'

[DELETE] /messages/{sessionId}/{jid}/{messageId}

Delete message for everyone

Delete message (only works for messages < 7 minutes old)

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Message deleted for everyone"
}

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/messages/session-01/[email protected]/MSG_ID_123" \
  -H "X-API-Key: your-api-key"

[PATCH] /messages/{sessionId}/{jid}/{messageId}

Edit a sent message

Edit text of a sent message

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "text": "Updated text message"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Message edited successfully"
}

cURL Example

bash
curl -X PATCH "http://localhost:3000/api/messages/session-01/[email protected]/MSG_ID_123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Updated text message"}'

📂 Chat

[GET] /chat/{sessionId}

Get chat list with contacts

Retrieve all contacts with last message for a session

Parameters

Responses

Response Example ( 200):

json
[
  {
    "jid": "[email protected]",
    "name": "John Doe",
    "notify": "string",
    "profilePic": "string"
  }
]

cURL Example

bash
curl -X GET "http://localhost:3000/api/chat/session-01" \
  -H "X-API-Key: your-api-key"

[GET] /chat/{sessionId}/{jid}

Get message history

Fetch up to 100 messages for a chat (enriched with participant info for groups)

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/chat/session-01/[email protected]" \
  -H "X-API-Key: your-api-key"

[PUT] /chat/{sessionId}/{jid}/read

Mark messages as read

Mark specific messages or entire chat as read using RESTful path parameters

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "messageIds": [
    "string"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Messages marked as read"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/[email protected]/read" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"messageIds":["string"]}'

[PUT] /chat/{sessionId}/{jid}/archive

Archive/unarchive chat

Archive or unarchive a chat using RESTful path parameters

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "archive": true
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Chat archived"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/[email protected]/archive" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"archive":true}'

[PUT] /chat/{sessionId}/{jid}/mute

Mute/unmute chat

Mute chat with optional duration (default 8 hours)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "mute": true,
  "duration": 3600
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Chat muted"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/[email protected]/mute" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"mute":true,"duration":3600}'

[PUT] /chat/{sessionId}/{jid}/pin

Pin/unpin chat

Pin or unpin a chat

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "pin": true
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Chat pinned"
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/[email protected]/pin" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pin":true}'

[POST] /chat/{sessionId}/{jid}/presence

Send presence (typing/recording)

Send presence status (typing, recording, online, etc.) to a chat

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "presence": "composing"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "message": "Presence 'composing' sent to [email protected]"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/[email protected]/presence" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"presence":"composing"}'

[POST] /chat/{sessionId}/{jid}/profile-picture

Get profile picture URL

Get profile picture URL for a contact or group

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "jid": "[email protected]",
  "profilePicUrl": "https://pps.whatsapp.net/...",
  "message": "No profile picture found"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/[email protected]/profile-picture" \
  -H "X-API-Key: your-api-key"

[POST] /chat/{sessionId}/check

Check if numbers exist on WhatsApp

Validate phone numbers (max 50 per request)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "numbers": [
    "628123456789",
    "628987654321"
  ]
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "results": [
    {
      "number": "string",
      "exists": true,
      "jid": "string",
      "error": "string"
    }
  ]
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/check" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["628123456789","628987654321"]}'

📂 Profile

[GET] /profile/{sessionId}

Get own profile

Fetch profile information of the connected WhatsApp account

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "success": true,
  "jid": "string",
  "status": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/profile/session-01" \
  -H "X-API-Key: your-api-key"

[PUT] /profile/{sessionId}/name

Update profile name

Update the WhatsApp display name (max 25 chars)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "name": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/profile/session-01/name" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

[PUT] /profile/{sessionId}/status

Update profile status

Update the WhatsApp about/status (max 139 chars)

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "status": "string"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/profile/session-01/status" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"status":"string"}'

[DELETE] /profile/{sessionId}/picture

Remove profile picture

Parameters

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/profile/session-01/picture" \
  -H "X-API-Key: your-api-key"

[PUT] /profile/{sessionId}/picture

Update profile picture

Upload a new profile picture

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( multipart/form-data)

Example:

json
{
  "file": "(binary)"
}

Responses

Response Fields ( 200):

Response Example ( 200):

json
{
  "status": true,
  "message": "Operation successful",
  "data": {
    "text": "Hello from WA-AKG!"
  }
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/profile/session-01/picture" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/file.jpg" \
  -F "type=image" \
  -F "caption=Hello"

📂 Auto Replies

[DELETE] /autoreplies/{sessionId}

Delete all autoreplies

Parameters

Responses

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/autoreplies/session-01" \
  -H "X-API-Key: your-api-key"

📂 Auto Reply

[GET] /autoreplies/{sessionId}

List auto-reply rules

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/autoreplies/session-01" \
  -H "X-API-Key: your-api-key"

[POST] /autoreplies/{sessionId}

Create auto-reply rule

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "keyword": "hello",
  "response": "Hi there! How can I help?",
  "matchType": "EXACT",
  "triggerType": "ALL",
  "isMedia": false
}

Responses

cURL Example

bash
curl -X POST "http://localhost:3000/api/autoreplies/session-01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"hello","response":"Hi there! How can I help?","matchType":"EXACT","triggerType":"ALL","isMedia":false}'

[DELETE] /autoreplies/{sessionId}/{replyId}

Delete auto-reply rule

Parameters

Responses

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/autoreplies/session-01/reply_01" \
  -H "X-API-Key: your-api-key"

[PUT] /autoreplies/{sessionId}/{replyId}

Update auto-reply rule

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "keyword": "hello",
  "response": "Hi there! How can I help?",
  "matchType": "EXACT",
  "triggerType": "ALL",
  "isMedia": false
}

Responses

cURL Example

bash
curl -X PUT "http://localhost:3000/api/autoreplies/session-01/reply_01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"hello","response":"Hi there! How can I help?","matchType":"EXACT","triggerType":"ALL","isMedia":false}'

📂 Scheduler

[DELETE] /scheduler/{sessionId}

Delete all scheduled messages for a session

Parameters

Responses

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/scheduler/session-01" \
  -H "X-API-Key: your-api-key"

[GET] /scheduler/{sessionId}

List scheduled messages

Parameters

Responses

cURL Example

bash
curl -X GET "http://localhost:3000/api/scheduler/session-01" \
  -H "X-API-Key: your-api-key"

[POST] /scheduler/{sessionId}

Create scheduled message

Parameters

Headers

 X-API-Key: your-api-key
Content-Type: application/json

Request Body ( application/json)

Example:

json
{
  "jid": "[email protected]",
  "content": "Reminder: Meeting in 10 mins",
  "sendAt": "2024-12-25T10:00:00.000Z",
  "mediaUrl": "https://example.com/image.jpg",
  "mediaType": "image"
}

Responses