WA-AKG API Documentation

WhatsApp AI Gateway — Complete API Reference

Professional WhatsApp Gateway REST API with 86 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

bashCopy
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

bashCopy
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):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "subject": "string"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "sessionId": "string"
}

Responses

cURL Example

bashCopy
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:

jsonCopy
{
  "inviteCode": "string"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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

bashCopy
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:

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

Responses

cURL Example

bashCopy
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:

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

Responses

cURL Example

bashCopy
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:

jsonCopy
{
  "description": "string"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "expiration": 0
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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

bashCopy
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

bashCopy
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:

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

Responses

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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):

jsonCopy
{
  "csrfToken": "string"
}

cURL Example

bashCopy
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):

jsonCopy
[
  {
    "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

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "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

bashCopy
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):

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

cURL Example

bashCopy
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

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "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

bashCopy
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):

jsonCopy
{
  "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

bashCopy
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):

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

cURL Example

bashCopy
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:

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

Responses

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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):

jsonCopy
{
  "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

bashCopy
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:

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

Responses

cURL Example

bashCopy
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:

jsonCopy
{
  "userId": "clx456ghi"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "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

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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}/{jid}/interactive

Send interactive message (Native Flow buttons, CTA, List)

Send modern WhatsApp Native Flow interactive messages including quick replies, CTA URL links, CTA call buttons, copy-to-clipboard code, and single select lists.

Parameters

Headers

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

Request Body (application/json)

Example:

jsonCopy
{
  "title": "Interactive Message Title",
  "body": "Hello! Please select one of the options below:",
  "footer": "Powered by WA-AKG",
  "header": {
    "title": "Announcement",
    "image": {
      "url": "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800"
    }
  },
  "buttons": [
    {
      "type": "quick_reply",
      "displayText": "Confirm Order",
      "id": "btn_confirm",
      "url": "https://example.com",
      "phoneNumber": "+628123456789",
      "copyCode": "PROMO2026",
      "title": "Menu List",
      "sections": [
        {
          "title": "Available Packages",
          "rows": [
            {
              "id": "pkg_basic",
              "title": "Basic Plan",
              "description": "Affordable starter package"
            }
          ]
        }
      ]
    }
  ]
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
curl -X POST "http://localhost:3000/api/messages/session-01/[email protected]/interactive" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Interactive Message Title","body":"Hello! Please select one of the options below:","footer":"Powered by WA-AKG","header":{"title":"Announcement","image":{"url":"https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800"}},"buttons":[{"type":"quick_reply","displayText":"Confirm Order","id":"btn_confirm","url":"https://example.com","phoneNumber":"+628123456789","copyCode":"PROMO2026","title":"Menu List","sections":[{"title":"Available Packages","rows":[{"id":"pkg_basic","title":"Basic Plan","description":"Affordable starter package"}]}]}]}'

[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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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}'

[GET] /messages/{sessionId}/broadcast/history

Get broadcast history

Retrieve list of past broadcasts with status, sent/failed counts (persisted in DB)

Parameters

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "status": true,
  "data": [
    {
      "id": "string",
      "sessionId": "string",
      "message": "string",
      "total": 0,
      "sent": 0,
      "failed": 0,
      "status": "running",
      "delay": 0,
      "startedAt": "2026-01-15T08:00:00.000Z",
      "completedAt": "2026-01-15T08:00:00.000Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}

cURL Example

bashCopy
curl -X GET "http://localhost:3000/api/messages/session-01/broadcast/history?limit=value&offset=value" \
  -H "X-API-Key: your-api-key"

[GET] /messages/{sessionId}/broadcast/history/{logId}

Get broadcast detail

Retrieve full detail of a specific broadcast including per-recipient status

Parameters

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "status": true,
  "data": {
    "id": "string",
    "sessionId": "string",
    "message": "string",
    "total": 0,
    "sent": 0,
    "failed": 0,
    "status": "string",
    "delay": 0,
    "startedAt": "2026-01-15T08:00:00.000Z",
    "completedAt": "2026-01-15T08:00:00.000Z",
    "recipients": [
      {
        "id": "string",
        "jid": "string",
        "status": "pending",
        "error": "string",
        "sentAt": "2026-01-15T08:00:00.000Z"
      }
    ]
  }
}

cURL Example

bashCopy
curl -X GET "http://localhost:3000/api/messages/session-01/broadcast/history/value" \
  -H "X-API-Key: your-api-key"

[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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "success": true
}

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "success": true
}

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "success": true
}

cURL Example

bashCopy
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

bashCopy
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:

jsonCopy
{
  "emoji": "👍"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

jsonCopy
{
  "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

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "success": true
}

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

jsonCopy
{
  "success": true
}

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "text": "Updated text message"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "archive": true
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "pin": true
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "presence": "composing"
}

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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:

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

Responses

Response Fields (200):

Response Example (200):

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

cURL Example

bashCopy
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):

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

cURL Example

bashCopy
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:

jsonCopy
{
  "name": "string"
}

Responses