WA-AKG API Documentation

WhatsApp AI Gateway — Complete API Reference

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

🔐 Authentication

All endpoints require one of the following authentication methods:

Method	Header / Cookie	Example
API Key	`X-API-Key` (header)	`X-API-Key: your-api-key-here`
Session Cookie	`next-auth.session-token` (cookie)	Automatically managed by browser

📋 Common Parameters

Parameter	Format	Example
`sessionId`	Unique session identifier	`session-01`
`jid` (Personal)	`{countryCode}{number}@s.whatsapp.net`	`628123456789@s.whatsapp.net`
`jid` (Group)	`{groupId}@g.us`	`120363123456789@g.us`

📂 Web Authentication

[GET] /auth/session

Get current web session

Check if the user is authenticated in the web dashboard

Responses

Code	Description
`200`	Current session

Response Fields ( 200):

Field	Type	Required	Description
`user`	object	No	—
`expires`	string	No	—

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

Code	Description
`200`	CSRF Token

Response Fields ( 200):

Field	Type	Required	Description
`csrfToken`	string	No	—

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

Code	Description
`200`	List of sessions
`401`	Unauthorized - Invalid or missing API key

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`)

Field	Type	Required	Description
`name`	string	✅ Yes	Display name for the session
`sessionId`	string	No	Unique session ID (auto-generated if not provided)

Example:

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

Responses

Code	Description
`200`	Session created successfully
`400`	Invalid request body
`401`	Unauthorized - Invalid or missing API key

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`name`	string	No	—
`sessionId`	string	No	—
`status`	string	No	Options: `Connected`, `Disconnected`, `Connecting`
`userId`	string	No	—
`botConfig`	object, nullable	No	—
`webhooks`	array of object	No	—
`_count`	object, nullable	No	—
`createdAt`	string (date-time)	No	—
`updatedAt`	string (date-time)	No	—

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	Session ID

Responses

Code	Description
`200`	QR code generated
`400`	Already connected
`404`	QR not available yet

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`qr`	string	No	QR code string
`base64`	string	No	Base64 data URL for image

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Bot configuration retrieved

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`enabled`	boolean	No	—
`botMode`	string	No	Options: `OWNER`, `SPECIFIC`, `BLACKLIST`, `ALL`
`botAllowedJids`	array of string	No	—
`botBlockedJids`	array of string	No	—
`autoReplyMode`	string	No	Options: `OWNER`, `SPECIFIC`, `BLACKLIST`, `ALL`
`autoReplyAllowedJids`	array of string	No	—
`autoReplyBlockedJids`	array of string	No	—
`botName`	string	No	—
`enableSticker`	boolean	No	—
`enableVideoSticker`	boolean	No	—
`maxStickerDuration`	integer	No	—
`enablePing`	boolean	No	—
`enableUptime`	boolean	No	—
`removeBgApiKey`	string, nullable	No	—
`antiSpamEnabled`	boolean	No	Enable random delays to avoid WhatsApp bans
`spamLimit`	integer	No	Max messages allowed in the interval window (default 5)
`spamInterval`	integer	No	Time window in seconds (default 10)
`spamDelayMin`	integer	No	Min random delay in ms (default 1000)
`spamDelayMax`	integer	No	Max random delay in ms (default 3000)

Example:

json
{
  "enabled": true,
  "botMode": "BLACKLIST",
  "botBlockedJids": [
    "628123456789@s.whatsapp.net"
  ],
  "autoReplyMode": "SPECIFIC",
  "autoReplyAllowedJids": [
    "628123456789@s.whatsapp.net"
  ],
  "botName": "My Assistant",
  "enableSticker": true
}

Responses

Code	Description
`200`	Configuration updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`sessionId`	string	No	—
`enabled`	boolean	No	—
`botMode`	string	No	—
`botAllowedJids`	array of string	No	—
`autoReplyMode`	string	No	—
`autoReplyAllowedJids`	array of string	No	—
`botName`	string	No	—
`enableSticker`	boolean	No	—
`enableVideoSticker`	boolean	No	—
`maxStickerDuration`	integer	No	—
`enablePing`	boolean	No	—
`enableUptime`	boolean	No	—
`removeBgApiKey`	string, nullable	No	—
`createdAt`	string (date-time)	No	—
`updatedAt`	string (date-time)	No	—

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":["628123456789@s.whatsapp.net"],"autoReplyMode":"SPECIFIC","autoReplyAllowedJids":["628123456789@s.whatsapp.net"],"botName":"My Assistant","enableSticker":true}'

[GET] /sessions/{id}

Get session details

Get detailed information about a specific session including uptime and status

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Session details
`404`	Session not found

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—
`action`	path	✅ Yes	string	Options: `start`, `stop`, `restart`, `logout`

Responses

Code	Description
`200`	Action performed successfully
`400`	Invalid action
`500`	Action failed

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`config`	object	No	—

Example:

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

Responses

Code	Description
`200`	Settings updated

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

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Session deleted

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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"

📂 Messaging (Deprecated)

[POST] /chat/send

⚠️ DEPRECATED — ⚠️ DEPRECATED: Use POST /messages/{sessionId}/{jid}/send instead. This endpoint will be removed in a future version.\n\nUniversal endpoint for sending text, images, videos, documents, and stickers

[DEPRECATED] Send message (text/media/sticker)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`message`	object	✅ Yes	Message content (text, image, sticker, etc.)
`mentions`	array of string	No	List of JIDs to mention

Example:

json
{
  "sessionId": "sales-01",
  "jid": "628123456789@s.whatsapp.net",
  "message": {
    "text": "Hello from WA-AKG!"
  },
  "mentions": [
    "628123456789@s.whatsapp.net"
  ]
}

Responses

Code	Description
`200`	Message sent
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/chat/send" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"sales-01","jid":"628123456789@s.whatsapp.net","message":{"text":"Hello from WA-AKG!"},"mentions":["628123456789@s.whatsapp.net"]}'

[POST] /chat/{sessionId}/send

⚠️ DEPRECATED — ⚠️ DEPRECATED: Use POST /messages/{sessionId}/{jid}/send instead.

[DEPRECATED] Send message

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`jid`	string	✅ Yes	—
`message`	object	✅ Yes	—

Example:

json
{
  "jid": "string",
  "message": {
    "text": "Hello from WA-AKG!"
  }
}

Responses

Code	Description
`200`	Message sent

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/send" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jid":"string","message":{"text":"Hello from WA-AKG!"}}'

📂 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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	Session identifier
`jid`	path	✅ Yes	string	Recipient JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`message`	object	✅ Yes	Message content (text, image, sticker, etc.)
`mentions`	array of string	No	List of JIDs to mention (for group messages)

Example:

json
{
  "message": {
    "text": "Hello from WA-AKG!"
  },
  "mentions": [
    "628123456789@s.whatsapp.net"
  ]
}

Responses

Code	Description
`200`	Message sent successfully
`400`	Invalid request - jid and message are required
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found or disconnected
`500`	Failed to send message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/628123456789@s.whatsapp.net/send" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":{"text":"Hello from WA-AKG!"},"mentions":["628123456789@s.whatsapp.net"]}'

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

Send media (image/video/audio/document)

Send file using multipart/form-data

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	Session identifier
`jid`	path	✅ Yes	string	Recipient JID

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`file`	string (binary)	✅ Yes	—
`type`	string	✅ Yes	Options: `image`, `video`, `audio`, `voice`, `document`, `sticker` Default: `image`
`caption`	string	No	—

Example:

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

Responses

Code	Description
`200`	Media sent successfully
`400`	Bad Request - File missing
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send media
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`recipients`	array of string	✅ Yes	—
`message`	string	✅ Yes	—
`delay`	number	No	Optional delay (unused)

Example:

json
{
  "recipients": [
    "628123456789@s.whatsapp.net",
    "628987654321@s.whatsapp.net"
  ],
  "message": "Flash Sale! 50% off",
  "delay": 0
}

Responses

Code	Description
`200`	Broadcast started
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to start broadcast
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

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":["628123456789@s.whatsapp.net","628987654321@s.whatsapp.net"],"message":"Flash Sale! 50% off","delay":0}'

[POST] /messages/broadcast

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/broadcast instead. This endpoint will be removed in a future version.

Broadcast message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`recipients`	array of string	✅ Yes	—
`message`	string	✅ Yes	—
`delay`	number	No	Intended delay between messages (ms). Note: implementation uses additional random 10-20s delay. Default: `2000`

Example:

json
{
  "sessionId": "string",
  "recipients": [
    "628123456789@s.whatsapp.net",
    "628987654321@s.whatsapp.net"
  ],
  "message": "Flash Sale! 50% off",
  "delay": 0
}

Responses

Code	Description
`200`	Broadcast started (background processing)
`400`	Invalid request (validation error)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to start broadcast
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/broadcast" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","recipients":["628123456789@s.whatsapp.net","628987654321@s.whatsapp.net"],"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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`question`	string	✅ Yes	—
`options`	array of string	✅ Yes	—
`selectableCount`	integer	No	—

Example:

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

Responses

Code	Description
`200`	Poll sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send poll
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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/poll

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/poll instead. This endpoint will be removed in a future version.

Send poll message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`question`	string	✅ Yes	—
`options`	array of string	✅ Yes	—
`selectableCount`	integer	No	—

Example:

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

Responses

Code	Description
`200`	Poll sent
`400`	Invalid request (missing fields or options out of range)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send poll
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/poll" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`latitude`	number	✅ Yes	—
`longitude`	number	✅ Yes	—
`name`	string	No	—
`address`	string	No	—

Example:

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

Responses

Code	Description
`200`	Location sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send location
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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/location

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/location instead. This endpoint will be removed in a future version.

Send location (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`latitude`	number	✅ Yes	—
`longitude`	number	✅ Yes	—
`name`	string	No	—
`address`	string	No	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "latitude": -6.2088,
  "longitude": 106.8456,
  "name": "Office",
  "address": "Jakarta, Indonesia"
}

Responses

Code	Description
`200`	Location sent
`400`	Invalid request (missing fields or coordinates out of range)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send location
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/location" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","latitude":-6.2088,"longitude":106.8456,"name":"Office","address":"Jakarta, Indonesia"}'

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

Send contact card

Share one or multiple contact vCards

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`contacts`	array of object	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Contact sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send contact
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

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

[POST] /messages/contact

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/contact instead. This endpoint will be removed in a future version.

Send contact card (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`contacts`	array of object	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "contacts": [
    {
      "displayName": "string",
      "vcard": "string"
    }
  ]
}

Responses

Code	Description
`200`	Contact sent
`400`	Invalid request (missing fields or empty contacts)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send contact
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/contact" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","contacts":[{"displayName":"string","vcard":"string"}]}'

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

Download message media

Download media from a message (direct binary or redirect)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`messageId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Binary media file
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Cannot access session or message
`404`	Message not found or has no media

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"

[GET] /messages/{id}/media

⚠️ DEPRECATED — DEPRECATED: Use GET /messages/{sessionId}/{messageId}/media instead. This endpoint will be removed in a future version.

Download message media (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Binary media file
`400`	sessionId is required
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Cannot access session or message
`404`	Message not found or has no media

cURL Example

bash
curl -X GET "http://localhost:3000/api/messages/abc123/media?sessionId=session-01" \
  -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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—
`messageId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`emoji`	string	✅ Yes	Emoji or empty string to remove

Example:

json
{
  "emoji": "👍"
}

Responses

Code	Description
`200`	Reaction sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send reaction
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—
`messageId`	path	✅ Yes	string	ID of message to reply to

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`message`	object	✅ Yes	Message content — same format as /send (text, image, video, etc.)
`mentions`	array of string	No	JIDs to mention
`fromMe`	boolean	No	Whether the quoted message was sent by you Default: `false`

Example:

json
{
  "message": {
    "text": "Thanks for your message!"
  },
  "mentions": [
    "628123456789@s.whatsapp.net"
  ],
  "fromMe": true
}

Responses

Code	Description
`200`	Reply sent successfully
`400`	message is required
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send reply
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/sales-01/628123456789@s.whatsapp.net/3EB0ABCD1234567890/reply" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":{"text":"Thanks for your message!"},"mentions":["628123456789@s.whatsapp.net"],"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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`messageId`	string	✅ Yes	ID of the message to reply to
`message`	object	✅ Yes	Message content — same format as /send (text, image, video, etc.)
`mentions`	array of string	No	JIDs to mention
`fromMe`	boolean	No	Whether the quoted message was sent by you Default: `false`

Example:

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

Responses

Code	Description
`200`	Reply sent successfully
`400`	messageId and message required
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send reply
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—
`messageId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`star`	boolean	No	true to star, false to unstar Default: `true`
`fromMe`	boolean	No	Whether the message was sent by you Default: `false`

Example:

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

Responses

Code	Description
`200`	Star status updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to star/unstar message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`q`	query	No	string	Text to search for in message content
`jid`	query	No	string	Filter by chat JID
`type`	query	No	string	Filter by message type Options: `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`, `STICKER`, `LOCATION`, `CONTACT`
`fromMe`	query	No	boolean	Filter by sender (true=outgoing, false=incoming)
`page`	query	No	integer	Default: `1`
`limit`	query	No	integer	Default: `20`

Responses

Code	Description
`200`	Search results
`400`	q or jid is required
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found
`500`	Failed to search messages

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`data`	array of object	No	—
`pagination`	object	No	—

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&jid=628123456789@s.whatsapp.net&type=value&fromMe=value&page=value&limit=value" \
  -H "X-API-Key: your-api-key"

[POST] /messages/react

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/{messageId}/react instead. This endpoint will be removed in a future version.

React to message with emoji (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`messageId`	string	✅ Yes	—
`emoji`	string	✅ Yes	Emoji or empty string to remove

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "messageId": "3EB0ABCD1234567890",
  "emoji": "👍"
}

Responses

Code	Description
`200`	Reaction sent
`400`	Invalid request (missing fields)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send reaction
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "message": "Reaction sent"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/react" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","messageId":"3EB0ABCD1234567890","emoji":"👍"}'

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

Send list message

Send a formatted numbered list message

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`title`	string	✅ Yes	—
`options`	array of string	✅ Yes	—
`footer`	string	No	—

Example:

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

Responses

Code	Description
`200`	Message sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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/list

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/list instead. This endpoint will be removed in a future version.

Send list message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`title`	string	✅ Yes	—
`options`	array of string	✅ Yes	—
`footer`	string	No	—

Example:

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

Responses

Code	Description
`200`	List message sent
`400`	Missing fields or empty options
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send list message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/list" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`message`	string	✅ Yes	—
`count`	integer	No	Default: `10`
`delay`	integer	No	Delay in ms Default: `500`

Example:

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

Responses

Code	Description
`200`	Spam started
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to start spam
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/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/spam

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/spam instead. This endpoint will be removed in a future version.

Message bombing (Spam) (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`message`	string	✅ Yes	—
`count`	integer	No	Default: `10`
`delay`	integer	No	Delay in ms Default: `500`

Example:

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

Responses

Code	Description
`200`	Spam started
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to start spam
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "message": "Bombing 5 messages started"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/messages/spam" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`file`	string (binary)	✅ Yes	—
`pack`	string	No	Sticker pack name (default: WA-AKG)
`author`	string	No	Sticker author name (default: User)
`type`	string	No	Sticker crop type (default: full) Options: `full`, `crop`, `circle`
`quality`	integer	No	Image quality (default: 50)

Example:

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

Responses

Code	Description
`200`	Sticker sent
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to create sticker
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

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

[POST] /messages/sticker

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/{jid}/sticker instead. This endpoint will be removed in a future version.

Send sticker (DEPRECATED)

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`file`	string (binary)	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "file": "(binary)"
}

Responses

Code	Description
`200`	Sticker sent
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to create sticker
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`fromJid`	string	✅ Yes	Source chat JID
`messageId`	string	✅ Yes	—
`toJids`	array of string	✅ Yes	Recipient JIDs

Example:

json
{
  "fromJid": "628123456789@s.whatsapp.net",
  "messageId": "3EB0ABCD1234567890",
  "toJids": [
    "628987654321@s.whatsapp.net"
  ]
}

Responses

Code	Description
`200`	Message forwarded
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to forward message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

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":"628123456789@s.whatsapp.net","messageId":"3EB0ABCD1234567890","toJids":["628987654321@s.whatsapp.net"]}'

[POST] /messages/forward

⚠️ DEPRECATED — DEPRECATED: Use POST /messages/{sessionId}/forward instead. This endpoint will be removed in a future version.

Forward message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`fromJid`	string	✅ Yes	Source chat JID
`messageId`	string	✅ Yes	—
`toJids`	array of string	✅ Yes	Recipient JIDs

Example:

json
{
  "sessionId": "string",
  "fromJid": "string",
  "messageId": "string",
  "toJids": [
    "string"
  ]
}

Responses

Code	Description
`200`	Message forwarded
`400`	Invalid request (missing fields or empty recipients)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to forward message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "message": "Message forwarded to 1 recipient(s)"
}

cURL Example

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

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

Delete message for everyone

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

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—
`messageId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Message deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to delete message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/messages/session-01/628123456789@s.whatsapp.net/MSG_ID_123" \
  -H "X-API-Key: your-api-key"

[DELETE] /messages/delete

⚠️ DEPRECATED — DEPRECATED: Use DELETE /messages/{sessionId}/{jid}/{messageId} instead. This endpoint will be removed in a future version.

Delete message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`messageId`	string	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "messageId": "string"
}

Responses

Code	Description
`200`	Message deleted
`400`	Message too old (> 7 minutes) or missing fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to delete message
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/messages/delete" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","messageId":"string"}'

📂 Chat

[GET] /chat/{sessionId}

Get chat list with contacts

Retrieve all contacts with last message for a session

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Chat list

Response Example ( 200):

json
[
  {
    "jid": "628123456789@s.whatsapp.net",
    "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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Responses

Code	Description
`200`	Message history (max 100 messages)

cURL Example

bash
curl -X GET "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net" \
  -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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	Session identifier
`jid`	path	✅ Yes	string	URL-encoded WhatsApp JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`messageIds`	array of string	No	Optional: specific message IDs to mark as read. If not provided, marks entire chat as read

Example:

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

Responses

Code	Description
`200`	Messages marked as read
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to mark messages as read
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`archive`	boolean	✅ Yes	true to archive, false to unarchive

Example:

json
{
  "archive": true
}

Responses

Code	Description
`200`	Chat archived/unarchived
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to archive/unarchive chat
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`mute`	boolean	✅ Yes	—
`duration`	integer	No	Duration in seconds (default: 8 hours)

Example:

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

Responses

Code	Description
`200`	Chat muted/unmuted
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to mute/unmute chat
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`pin`	boolean	✅ Yes	—

Example:

json
{
  "pin": true
}

Responses

Code	Description
`200`	Chat pinned/unpinned
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to pin/unpin chat
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`presence`	string	✅ Yes	Options: `composing`, `recording`, `paused`, `available`, `unavailable`

Example:

json
{
  "presence": "composing"
}

Responses

Code	Description
`200`	Presence sent
`400`	Missing required fields or invalid presence
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to send presence
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "message": "Presence 'composing' sent to 628123456789@s.whatsapp.net"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	URL-encoded JID

Responses

Code	Description
`200`	Profile picture URL
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to fetch profile picture
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`jid`	string	No	—
`profilePicUrl`	string, nullable	No	—
`message`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "jid": "628123456789@s.whatsapp.net",
  "profilePicUrl": "https://pps.whatsapp.net/...",
  "message": "No profile picture found"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`numbers`	array of string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Validation results
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to check numbers
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`results`	array of object	No	—

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"]}'

[POST] /chat/check

⚠️ DEPRECATED — DEPRECATED: Use POST /chat/{sessionId}/check instead. This endpoint will be removed in a future version.

Check numbers (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`numbers`	array of string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Validation results

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`results`	array of object	No	—

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/check" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","numbers":["628123456789","628987654321"]}'

[PUT] /chat/read

⚠️ DEPRECATED — DEPRECATED: Use PUT /chat/{sessionId}/{jid}/read instead. This endpoint will be removed in a future version.

Mark messages as read (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`messageIds`	array of string	No	Optional: specific message IDs to mark

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "messageIds": [
    "string"
  ]
}

Responses

Code	Description
`200`	Marked as read

cURL Example

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

[PUT] /chat/archive

⚠️ DEPRECATED — DEPRECATED: Use PUT /chat/{sessionId}/{jid}/archive instead. This endpoint will be removed in a future version.

Archive/unarchive chat (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`archive`	boolean	✅ Yes	true to archive, false to unarchive

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "archive": true
}

Responses

Code	Description
`200`	Chat archived/unarchived

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/archive" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","archive":true}'

[PUT] /chat/mute

⚠️ DEPRECATED — DEPRECATED: Use PUT /chat/{sessionId}/{jid}/mute instead. This endpoint will be removed in a future version.

Mute/unmute chat (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`mute`	boolean	✅ Yes	—
`duration`	integer	No	Duration in seconds (default: 8 hours)

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "mute": true,
  "duration": 3600
}

Responses

Code	Description
`200`	Chat muted/unmuted

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/mute" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","mute":true,"duration":3600}'

[PUT] /chat/pin

⚠️ DEPRECATED — DEPRECATED: Use PUT /chat/{sessionId}/{jid}/pin instead. This endpoint will be removed in a future version.

Pin/unpin chat (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`pin`	boolean	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "pin": true
}

Responses

Code	Description
`200`	Chat pinned/unpinned

cURL Example

bash
curl -X PUT "http://localhost:3000/api/chat/pin" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","pin":true}'

[POST] /chat/presence

⚠️ DEPRECATED — DEPRECATED: Use POST /chat/{sessionId}/{jid}/presence instead. This endpoint will be removed in a future version.

Send presence (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`presence`	string	✅ Yes	Options: `composing`, `recording`, `paused`, `available`, `unavailable`

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "presence": "composing"
}

Responses

Code	Description
`200`	Presence sent

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/presence" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","presence":"composing"}'

[POST] /chat/profile-picture

⚠️ DEPRECATED — DEPRECATED: Use POST /chat/{sessionId}/{jid}/profile-picture instead. This endpoint will be removed in a future version.

Get profile picture URL (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Profile picture URL

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`jid`	string	No	—
`profilePicUrl`	string, nullable	No	—

Response Example ( 200):

json
{
  "success": true,
  "jid": "string",
  "profilePicUrl": "string"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/chat/profile-picture" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string"}'

📂 Groups

[GET] /groups/{sessionId}

List all groups

Get all groups associated with the session

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of groups
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Resource not found
`500`	Failed to fetch groups

Response Example ( 200):

json
[
  {
    "id": "string",
    "subject": "string",
    "desc": "string",
    "owner": "string",
    "size": 0,
    "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"

[GET] /groups

⚠️ DEPRECATED — DEPRECATED: Use GET /groups/{sessionId} instead. This endpoint will be removed in a future version.

List all groups (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	List of groups

cURL Example

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

[POST] /groups/{sessionId}/create

Create new group

Create a new group with specified participants

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`subject`	string	✅ Yes	—
`participants`	array of string	✅ Yes	—

Example:

json
{
  "subject": "VIP Customers",
  "participants": [
    "628123456789@s.whatsapp.net"
  ]
}

Responses

Code	Description
`200`	Group created
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to create group
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`group`	object	No	—

Response Example ( 200):

json
{
  "success": true,
  "group": {
    "id": "string",
    "subject": "string",
    "desc": "string",
    "owner": "string",
    "size": 0,
    "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":["628123456789@s.whatsapp.net"]}'

[POST] /groups/create

⚠️ DEPRECATED — DEPRECATED: Use POST /groups/{sessionId}/create instead. This endpoint will be removed in a future version.

Create new group (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`subject`	string	✅ Yes	—
`participants`	array of string	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "subject": "VIP Customers",
  "participants": [
    "628123456789@s.whatsapp.net"
  ]
}

Responses

Code	Description
`200`	Group created

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/create" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","subject":"VIP Customers","participants":["628123456789@s.whatsapp.net"]}'

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

Update group subject

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`subject`	string	✅ Yes	—

Example:

json
{
  "subject": "string"
}

Responses

Code	Description
`200`	Subject updated
`400`	Invalid subject
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to update subject

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`subject`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	URL-encoded group JID

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`subject`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Subject updated
`400`	Invalid request (missing fields or subject too long)
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to update group subject
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`subject`	string	No	—

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/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`action`	string	✅ Yes	Options: `add`, `remove`, `promote`, `demote`
`participants`	array of string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Members updated
`400`	Invalid action
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to update members

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`result`	array of object	No	—

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/628123456789@s.whatsapp.net/members" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"action":"add","participants":["string"]}'

[PUT] /groups/{jid}/members

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/members instead. This endpoint will be removed in a future version.

Manage group members (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`action`	string	✅ Yes	Options: `add`, `remove`, `promote`, `demote`
`participants`	array of string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Members updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/members" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","action":"add","participants":["string"]}'

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

Get invite code

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Invite code
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to get code

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`inviteCode`	string	No	—
`inviteUrl`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/invite" \
  -H "X-API-Key: your-api-key"

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

Revoke invite code

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Invite revoked
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to revoke code

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`newInviteCode`	string	No	—
`inviteUrl`	string	No	—

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/628123456789@s.whatsapp.net/invite" \
  -H "X-API-Key: your-api-key"

[GET] /groups/{jid}/invite

⚠️ DEPRECATED — DEPRECATED: Use GET /groups/{sessionId}/{jid}/invite instead. This endpoint will be removed in a future version.

Get invite code (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Invite code

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`inviteCode`	string	No	—
`inviteUrl`	string	No	—

Response Example ( 200):

json
{
  "success": true,
  "inviteCode": "string",
  "inviteUrl": "https://chat.whatsapp.com/AbCdEfGh"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/invite?sessionId=session-01" \
  -H "X-API-Key: your-api-key"

[PUT] /groups/{jid}/invite

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/invite instead. This endpoint will be removed in a future version.

Revoke invite code (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—

Example:

json
{
  "sessionId": "string"
}

Responses

Code	Description
`200`	Invite code revoked, new code generated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/invite" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string"}'

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

Get group details

Get detailed group information

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Group details
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Resource not found
`500`	Failed to fetch details

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`subject`	string	No	—
`subjectOwner`	string	No	—
`subjectTime`	number	No	—
`desc`	string	No	—
`descOwner`	string	No	—
`descId`	string	No	—
`owner`	string	No	—

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/628123456789@s.whatsapp.net" \
  -H "X-API-Key: your-api-key"

[GET] /groups/{jid}

⚠️ DEPRECATED — DEPRECATED: Use GET /groups/{sessionId}/{jid} instead. This endpoint will be removed in a future version.

Get group details (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Group details
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Group not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`subject`	string	No	—
`subjectOwner`	string	No	—
`subjectTime`	integer	No	—
`size`	integer	No	—
`creation`	integer	No	—
`owner`	string	No	—
`desc`	string	No	—
`descId`	string	No	—
`restrict`	boolean	No	—
`announce`	boolean	No	—
`participants`	array of object	No	—
`ephemeralDuration`	integer	No	—
`inviteCode`	string	No	—
`pictureUrl`	string, nullable	No	—

Response Example ( 200):

json
{
  "id": "string",
  "subject": "string",
  "subjectOwner": "string",
  "subjectTime": 0,
  "size": 0,
  "creation": 0,
  "owner": "string",
  "desc": "string",
  "descId": "string",
  "restrict": true,
  "announce": true,
  "participants": [
    {
      "id": "string",
      "admin": "string"
    }
  ],
  "ephemeralDuration": 0,
  "inviteCode": "string",
  "pictureUrl": "string"
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/groups/628123456789@s.whatsapp.net?sessionId=session-01" \
  -H "X-API-Key: your-api-key"

[POST] /groups/{jid}/leave

Leave group

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—

Example:

json
{
  "sessionId": "string"
}

Responses

Code	Description
`200`	Left group

cURL Example

bash
curl -X POST "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`inviteCode`	string	✅ Yes	—

Example:

json
{
  "inviteCode": "string"
}

Responses

Code	Description
`200`	Group invite accepted
`400`	Invalid/Expired code
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to accept invite
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`groupJid`	string	No	—

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

[POST] /groups/invite/accept

⚠️ DEPRECATED — DEPRECATED: Use POST /groups/{sessionId}/invite/accept instead. This endpoint will be removed in a future version.

Accept group invite (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`inviteCode`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Group invite accepted

cURL Example

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

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

Update group picture

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`file`	string (binary)	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Picture updated

cURL Example

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

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

Remove group picture

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Picture removed

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/picture" \
  -H "X-API-Key: your-api-key"

[PUT] /groups/{jid}/picture

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/picture instead. This endpoint will be removed in a future version.

Update group picture (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`sessionId`	string	No	—
`file`	string (binary)	No	—

Example:

json
{
  "sessionId": "string",
  "file": "(binary)"
}

Responses

Code	Description
`200`	Picture updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/picture" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/file.jpg" \
  -F "type=image" \
  -F "caption=Hello"

[DELETE] /groups/{jid}/picture

⚠️ DEPRECATED — DEPRECATED: Use DELETE /groups/{sessionId}/{jid}/picture instead. This endpoint will be removed in a future version.

Remove group picture (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Picture removed

cURL Example

bash
curl -X DELETE "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/picture?sessionId=session-01" \
  -H "X-API-Key: your-api-key"

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

Update group settings

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`setting`	string	✅ Yes	announcement (admins only send), not_announcement (all send), locked (admins only edit), unlocked (all edit) Options: `announcement`, `not_announcement`, `locked`, `unlocked`
`value`	boolean	No	Ignored but required

Example:

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

Responses

Code	Description
`200`	Settings updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"setting":"announcement","value":true}'

[PUT] /groups/{jid}/settings

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/settings instead. This endpoint will be removed in a future version.

Update group settings (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`setting`	string	✅ Yes	announcement (admins only send), not_announcement (all send), locked (admins only edit), unlocked (all edit) Options: `announcement`, `not_announcement`, `locked`, `unlocked`
`value`	boolean	✅ Yes	Ignored but required

Example:

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

Responses

Code	Description
`200`	Settings updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","setting":"announcement","value":true}'

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

Update group description

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`description`	string	No	—

Example:

json
{
  "description": "string"
}

Responses

Code	Description
`200`	Description updated
`400`	Invalid input
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to update

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`description`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/description" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"description":"string"}'

[PUT] /groups/{jid}/description

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/description instead. This endpoint will be removed in a future version.

Update group description (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`description`	string	No	—

Example:

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

Responses

Code	Description
`200`	Group description updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/description" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","description":"string"}'

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

Toggle disappearing messages

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`expiration`	integer	✅ Yes	Options: `0`, `86400`, `604800`, `7776000`

Example:

json
{
  "expiration": 0
}

Responses

Code	Description
`200`	Ephemeral toggled
`400`	Invalid expiration
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to toggle

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`expiration`	integer	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/session-01/628123456789@s.whatsapp.net/ephemeral" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"expiration":0}'

[PUT] /groups/{jid}/ephemeral

⚠️ DEPRECATED — DEPRECATED: Use PUT /groups/{sessionId}/{jid}/ephemeral instead. This endpoint will be removed in a future version.

Toggle disappearing messages (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`expiration`	integer	✅ Yes	0 (off), 86400 (24h), 604800 (7d), 7776000 (90d) Options: `0`, `86400`, `604800`, `7776000`

Example:

json
{
  "sessionId": "string",
  "expiration": 0
}

Responses

Code	Description
`200`	Ephemeral settings updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/groups/628123456789@s.whatsapp.net/ephemeral" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","expiration":0}'

📂 Contacts

[GET] /contacts/{sessionId}

List contacts

Get all contacts with search and pagination

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`page`	query	No	integer	Default: `1`
`limit`	query	No	integer	Default: `10`
`search`	query	No	string	Search by name, notify, jid

Responses

Code	Description
`200`	Paginated contacts

Response Fields ( 200):

Field	Type	Required	Description
`data`	array of object	No	—
`meta`	object	No	—

Response Example ( 200):

json
{
  "data": [
    {
      "jid": "628123456789@s.whatsapp.net",
      "name": "John Doe",
      "notify": "string",
      "profilePic": "string"
    }
  ],
  "meta": {
    "total": 0,
    "page": 0,
    "limit": 0,
    "totalPages": 0
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/contacts/session-01?page=value&limit=value&search=value" \
  -H "X-API-Key: your-api-key"

[GET] /contacts

⚠️ DEPRECATED — DEPRECATED: Use GET /contacts/{sessionId} instead. This endpoint will be removed in a future version.

List contacts (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—
`page`	query	No	integer	Default: `1`
`limit`	query	No	integer	Default: `10`
`search`	query	No	string	Search by name, notify, jid

Responses

Code	Description
`200`	Paginated contacts

Response Fields ( 200):

Field	Type	Required	Description
`data`	array of object	No	—
`meta`	object	No	—

Response Example ( 200):

json
{
  "data": [
    {
      "jid": "628123456789@s.whatsapp.net",
      "name": "John Doe",
      "notify": "string",
      "profilePic": "string"
    }
  ],
  "meta": {
    "total": 0,
    "page": 0,
    "limit": 0,
    "totalPages": 0
  }
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/contacts?sessionId=session-01&page=value&limit=value&search=value" \
  -H "X-API-Key: your-api-key"

[POST] /contacts/{sessionId}/{jid}/block

Block contact

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Contact blocked
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to block contact

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/contacts/session-01/628123456789@s.whatsapp.net/block" \
  -H "X-API-Key: your-api-key"

[POST] /contacts/block

⚠️ DEPRECATED — DEPRECATED: Use POST /contacts/{sessionId}/{jid}/block instead. This endpoint will be removed in a future version.

Block contact (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Contact blocked

cURL Example

bash
curl -X POST "http://localhost:3000/api/contacts/block" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string"}'

[POST] /contacts/{sessionId}/{jid}/unblock

Unblock contact

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Contact unblocked
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to unblock contact

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/contacts/session-01/628123456789@s.whatsapp.net/unblock" \
  -H "X-API-Key: your-api-key"

[POST] /contacts/unblock

⚠️ DEPRECATED — DEPRECATED: Use POST /contacts/{sessionId}/{jid}/unblock instead. This endpoint will be removed in a future version.

Unblock contact (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Contact unblocked

cURL Example

bash
curl -X POST "http://localhost:3000/api/contacts/unblock" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string"}'

📂 Profile

[GET] /profile/{sessionId}

Get own profile

Fetch profile information of the connected WhatsApp account

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Profile info
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`jid`	string	No	—
`status`	object	No	—

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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	✅ Yes	—

Example:

json
{
  "name": "string"
}

Responses

Code	Description
`200`	Name updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`status`	string	✅ Yes	—

Example:

json
{
  "status": "string"
}

Responses

Code	Description
`200`	Status updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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

[PUT] /profile/{sessionId}/picture

Update profile picture

Upload a new profile picture

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`file`	string (binary)	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Picture updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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"

[DELETE] /profile/{sessionId}/picture

Remove profile picture

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Picture removed
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/name

⚠️ DEPRECATED — DEPRECATED: Use PUT /profile/{sessionId}/name instead.

Update profile name (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`name`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Profile name updated

cURL Example

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

[PUT] /profile/status

⚠️ DEPRECATED — DEPRECATED: Use PUT /profile/{sessionId}/status instead.

Update profile status (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`status`	string	✅ Yes	—

Example:

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

Responses

Code	Description
`200`	Profile status updated

cURL Example

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

[PUT] /profile/picture

⚠️ DEPRECATED — DEPRECATED: Use PUT /profile/{sessionId}/picture instead.

Update profile picture (DEPRECATED)

Headers

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

Request Body ( `multipart/form-data`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`file`	string (binary)	✅ Yes	—

Example:

json
{
  "sessionId": "string",
  "file": "(binary)"
}

Responses

Code	Description
`200`	Profile picture updated

cURL Example

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

[DELETE] /profile/picture

⚠️ DEPRECATED — DEPRECATED: Use DELETE /profile/{sessionId}/picture instead.

Remove profile picture (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Profile picture removed

cURL Example

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

[GET] /profile

⚠️ DEPRECATED — DEPRECATED: Use GET /profile/{sessionId} instead.

Get own profile (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Profile information

cURL Example

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

📂 Auto Reply

[GET] /autoreplies/{sessionId}

List auto-reply rules

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of auto-reply rules
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found

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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`keyword`	string	✅ Yes	—
`response`	string	✅ Yes	—
`matchType`	string	No	Options: `EXACT`, `CONTAINS`, `STARTS_WITH`, `REGEX`
`isMedia`	boolean	No	—
`mediaUrl`	string	No	—
`triggerType`	string	No	Options: `ALL`, `GROUP`, `PRIVATE`

Example:

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

Responses

Code	Description
`200`	Rule created
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied

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

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

Update auto-reply rule

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`replyId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`keyword`	string	✅ Yes	—
`response`	string	✅ Yes	—
`isMedia`	boolean	No	—
`mediaUrl`	string	No	—
`triggerType`	string	No	Options: `ALL`, `GROUP`, `PRIVATE`

Example:

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

Responses

Code	Description
`200`	Rule updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Rule not found

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

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

Delete auto-reply rule

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`replyId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Rule deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Rule not found

cURL Example

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

[GET] /autoreplies

⚠️ DEPRECATED — DEPRECATED: Use GET /autoreplies/{sessionId} instead.

List auto-reply rules (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	List of auto-reply rules

cURL Example

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

[POST] /autoreplies

⚠️ DEPRECATED — DEPRECATED: Use POST /autoreplies/{sessionId} instead.

Create auto-reply rule (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`keyword`	string	✅ Yes	—
`response`	string	✅ Yes	—
`matchType`	string	No	Options: `EXACT`, `CONTAINS`, `STARTS_WITH` Default: `EXACT`

Example:

json
{
  "sessionId": "string",
  "keyword": "price",
  "response": "Our prices start at $10",
  "matchType": "EXACT"
}

Responses

Code	Description
`200`	Rule created

cURL Example

bash
curl -X POST "http://localhost:3000/api/autoreplies" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","keyword":"price","response":"Our prices start at $10","matchType":"EXACT"}'

[GET] /autoreplies/{id}

⚠️ DEPRECATED — DEPRECATED: Use GET /autoreplies/{sessionId}/{replyId} instead.

Get auto-reply rule (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Auto-reply rule details

cURL Example

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

[PUT] /autoreplies/{id}

⚠️ DEPRECATED — DEPRECATED: No direct replacement yet, delete and recreate.

Update auto-reply rule (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`keyword`	string	No	—
`response`	string	No	—
`matchType`	string	No	Options: `EXACT`, `CONTAINS`, `STARTS_WITH`

Example:

json
{
  "keyword": "string",
  "response": "string",
  "matchType": "EXACT"
}

Responses

Code	Description
`200`	Rule updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/autoreplies/abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"string","response":"string","matchType":"EXACT"}'

[DELETE] /autoreplies/{id}

⚠️ DEPRECATED — DEPRECATED: Use DELETE /autoreplies/{sessionId}/{replyId} instead.

Delete auto-reply rule (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Rule deleted

cURL Example

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

📂 Scheduler

[GET] /scheduler/{sessionId}

List scheduled messages

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of scheduled messages
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found

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

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`jid`	string	✅ Yes	—
`content`	string	✅ Yes	—
`sendAt`	string (date-time)	✅ Yes	—
`mediaUrl`	string	No	—
`mediaType`	string	No	Options: `image`, `video`, `document`

Example:

json
{
  "jid": "628123456789@s.whatsapp.net",
  "content": "Reminder: Meeting in 10 mins",
  "sendAt": "2024-12-25T10:00:00.000Z",
  "mediaUrl": "https://example.com/image.jpg",
  "mediaType": "image"
}

Responses

Code	Description
`200`	Scheduled message created
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied

cURL Example

bash
curl -X POST "http://localhost:3000/api/scheduler/session-01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jid":"628123456789@s.whatsapp.net","content":"Reminder: Meeting in 10 mins","sendAt":"2024-12-25T10:00:00.000Z","mediaUrl":"https://example.com/image.jpg","mediaType":"image"}'

[PUT] /scheduler/{sessionId}/{scheduleId}

Update scheduled message

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`scheduleId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`jid`	string	✅ Yes	—
`content`	string	✅ Yes	—
`sendAt`	string (date-time)	✅ Yes	—
`mediaUrl`	string	No	—
`mediaType`	string	No	Options: `image`, `video`, `document`

Example:

json
{
  "jid": "628123456789@s.whatsapp.net",
  "content": "Updated meeting reminder",
  "sendAt": "2024-12-25T11:00:00.000Z",
  "mediaUrl": "https://example.com/image.jpg",
  "mediaType": "image"
}

Responses

Code	Description
`200`	Message updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Message not found

cURL Example

bash
curl -X PUT "http://localhost:3000/api/scheduler/session-01/sched_01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jid":"628123456789@s.whatsapp.net","content":"Updated meeting reminder","sendAt":"2024-12-25T11:00:00.000Z","mediaUrl":"https://example.com/image.jpg","mediaType":"image"}'

[DELETE] /scheduler/{sessionId}/{scheduleId}

Delete scheduled message

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`scheduleId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Message deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Message not found

cURL Example

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

[GET] /scheduler

⚠️ DEPRECATED — DEPRECATED: Use GET /scheduler/{sessionId} instead.

List scheduled messages (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	List of scheduled messages
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found
`500`	Internal Server Error

Response Example ( 200):

json
[
  {
    "id": "string",
    "sessionId": "string",
    "jid": "string",
    "content": "string",
    "sendAt": "2026-01-15T08:00:00.000Z",
    "status": "PENDING"
  }
]

cURL Example

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

[POST] /scheduler

⚠️ DEPRECATED — DEPRECATED: Use POST /scheduler/{sessionId} instead.

Schedule message (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`jid`	string	✅ Yes	—
`content`	string	✅ Yes	—
`sendAt`	string (date-time)	✅ Yes	—
`mediaUrl`	string, nullable	No	—

Example:

json
{
  "sessionId": "string",
  "jid": "string",
  "content": "string",
  "sendAt": "2024-01-18T10:00:00",
  "mediaUrl": "string"
}

Responses

Code	Description
`200`	Message scheduled
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`sessionId`	string	No	—
`jid`	string	No	—
`content`	string	No	—
`sendAt`	string (date-time)	No	—
`status`	string	No	—

Response Example ( 200):

json
{
  "id": "string",
  "sessionId": "string",
  "jid": "string",
  "content": "string",
  "sendAt": "2026-01-15T08:00:00.000Z",
  "status": "PENDING"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/scheduler" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","jid":"string","content":"string","sendAt":"2024-01-18T10:00:00","mediaUrl":"string"}'

[DELETE] /scheduler/{id}

⚠️ DEPRECATED — DEPRECATED: Use DELETE /scheduler/{sessionId}/{scheduleId} instead.

Delete scheduled message (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Scheduled message deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Message not found
`500`	Internal server error

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/scheduler/abc123" \
  -H "X-API-Key: your-api-key"

📂 Webhooks

[GET] /webhooks/{sessionId}

List webhooks for a session

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of webhooks
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied

cURL Example

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

[POST] /webhooks/{sessionId}

Create a webhook

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	✅ Yes	—
`url`	string	✅ Yes	—
`secret`	string	No	—
`events`	array of string	✅ Yes	—

Example:

json
{
  "name": "string",
  "url": "string",
  "secret": "string",
  "events": [
    "string"
  ]
}

Responses

Code	Description
`200`	Webhook created
`400`	Invalid input
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied

cURL Example

bash
curl -X POST "http://localhost:3000/api/webhooks/session-01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","url":"string","secret":"string","events":["string"]}'

[PUT] /webhooks/{sessionId}/{id}

Update webhook

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	No	—
`url`	string	No	—
`secret`	string	No	—
`events`	array of string	No	—
`isActive`	boolean	No	—

Example:

json
{
  "name": "string",
  "url": "string",
  "secret": "string",
  "events": [
    "string"
  ],
  "isActive": true
}

Responses

Code	Description
`200`	Webhook updated
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Webhook not found

cURL Example

bash
curl -X PUT "http://localhost:3000/api/webhooks/session-01/abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","url":"string","secret":"string","events":["string"],"isActive":true}'

[DELETE] /webhooks/{sessionId}/{id}

Delete webhook

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Webhook deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Webhook not found

cURL Example

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

[GET] /webhooks

⚠️ DEPRECATED —

List webhooks (DEPRECATED)

Responses

Code	Description
`200`	List of webhooks

cURL Example

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

[POST] /webhooks

⚠️ DEPRECATED —

Create webhook (DEPRECATED)

Responses

Code	Description
`200`	Webhook created

cURL Example

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

[PATCH] /webhooks/{id}

⚠️ DEPRECATED —

Update webhook (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	No	—
`url`	string (uri)	No	—
`secret`	string	No	—
`sessionId`	string	No	—
`events`	array of string	No	—
`isActive`	boolean	No	—

Example:

json
{
  "name": "string",
  "url": "string",
  "secret": "string",
  "sessionId": "string",
  "events": [
    "string"
  ],
  "isActive": true
}

Responses

Code	Description
`200`	Webhook updated
`401`	Unauthorized - Invalid or missing API key
`404`	Webhook not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`name`	string	No	—
`url`	string	No	—
`secret`	string	No	—
`events`	array of string	No	—
`isActive`	boolean	No	—
`sessionId`	string	No	—
`userId`	string	No	—
`createdAt`	string (date-time)	No	—
`updatedAt`	string (date-time)	No	—

Response Example ( 200):

json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "secret": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "sessionId": "string",
  "userId": "string",
  "createdAt": "2026-01-15T08:00:00.000Z",
  "updatedAt": "2026-01-15T08:00:00.000Z"
}

cURL Example

bash
curl -X PATCH "http://localhost:3000/api/webhooks/abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","url":"string","secret":"string","sessionId":"string","events":["string"],"isActive":true}'

[DELETE] /webhooks/{id}

Delete webhook

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Webhook deleted
`401`	Unauthorized - Invalid or missing API key
`404`	Webhook not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—

Response Example ( 200):

json
{
  "success": true
}

cURL Example

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

📂 Users

[GET] /users

List users (SUPERADMIN only)

Responses

Code	Description
`200`	List of users
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Internal Server Error

Response Example ( 200):

json
[
  {
    "id": "string",
    "name": "string",
    "email": "string",
    "role": "string",
    "createdAt": "2026-01-15T08:00:00.000Z",
    "_count": {
      "sessions": 0
    }
  }
]

cURL Example

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

[POST] /users

Create user (SUPERADMIN only)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	✅ Yes	—
`email`	string (email)	✅ Yes	—
`password`	string	✅ Yes	—
`role`	string	No	Options: `SUPERADMIN`, `OWNER`, `STAFF` Default: `OWNER`

Example:

json
{
  "name": "string",
  "email": "string",
  "password": "string",
  "role": "SUPERADMIN"
}

Responses

Code	Description
`200`	User created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`name`	string	No	—
`email`	string	No	—
`role`	string	No	—
`createdAt`	string (date-time)	No	—

Response Example ( 200):

json
{
  "id": "string",
  "name": "string",
  "email": "string",
  "role": "string",
  "createdAt": "2026-01-15T08:00:00.000Z"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/users" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","email":"string","password":"string","role":"SUPERADMIN"}'

[PATCH] /users/{id}

Update user (SUPERADMIN only)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	No	—
`email`	string	No	—
`password`	string	No	—
`role`	string	No	Options: `SUPERADMIN`, `OWNER`, `STAFF`

Example:

json
{
  "name": "string",
  "email": "string",
  "password": "string",
  "role": "SUPERADMIN"
}

Responses

Code	Description
`200`	User updated
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	User not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`user`	object	No	—

Response Example ( 200):

json
{
  "success": true,
  "user": {
    "id": "string",
    "email": "string",
    "name": "string",
    "role": "string",
    "emailVerified": "string",
    "image": "string",
    "createdAt": "2026-01-15T08:00:00.000Z",
    "updatedAt": "2026-01-15T08:00:00.000Z"
  }
}

cURL Example

bash
curl -X PATCH "http://localhost:3000/api/users/abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","email":"string","password":"string","role":"SUPERADMIN"}'

[DELETE] /users/{id}

Delete user (SUPERADMIN only)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	User deleted
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	User not found
`500`	Internal Server Error

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—

Response Example ( 200):

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

cURL Example

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

[GET] /user/api-key

Get current API key

Responses

Code	Description
`200`	Current API key
`401`	Unauthorized - Invalid or missing API key

Response Fields ( 200):

Field	Type	Required	Description
`apiKey`	string, nullable	No	—

Response Example ( 200):

json
{
  "apiKey": "string"
}

cURL Example

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

[POST] /user/api-key

Generate new API key

Responses

Code	Description
`200`	New API key generated
`401`	Unauthorized - Invalid or missing API key
`500`	Failed to generate API key

Response Fields ( 200):

Field	Type	Required	Description
`apiKey`	string	No	—

Response Example ( 200):

json
{
  "apiKey": "string"
}

cURL Example

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

[DELETE] /user/api-key

Revoke API key

Responses

Code	Description
`200`	API key revoked
`401`	Unauthorized - Invalid or missing API key
`500`	Failed to revoke API key

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/user/api-key" \
  -H "X-API-Key: your-api-key"

📂 Labels

[GET] /labels/{sessionId}

List labels

Get all labels with chat count

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of labels
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Session not found

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`labels`	array of object	No	—

Response Example ( 200):

json
{
  "success": true,
  "labels": [
    {
      "id": "string",
      "name": "string",
      "color": 0,
      "predefinedId": "string"
    }
  ]
}

cURL Example

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

[POST] /labels/{sessionId}

Create label

Create new label with color (0-19 index)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	✅ Yes	—
`color`	integer	No	Color index (0-19)

Example:

json
{
  "name": "Important",
  "color": 0
}

Responses

Code	Description
`200`	Label created
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to create label

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`label`	object	No	—

Response Example ( 200):

json
{
  "success": true,
  "label": {
    "id": "string",
    "name": "string",
    "color": 0,
    "predefinedId": "string"
  }
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/labels/session-01" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Important","color":0}'

[GET] /labels

⚠️ DEPRECATED — DEPRECATED: Use GET /labels/{sessionId} instead.

List all labels (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	List of labels

cURL Example

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

[POST] /labels

⚠️ DEPRECATED — DEPRECATED: Use POST /labels/{sessionId} instead.

Create label (DEPRECATED)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`name`	string	✅ Yes	—
`color`	integer	No	—

Example:

json
{
  "sessionId": "string",
  "name": "string",
  "color": 0
}

Responses

Code	Description
`200`	Label created

cURL Example

bash
curl -X POST "http://localhost:3000/api/labels" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","name":"string","color":0}'

[PUT] /labels/{sessionId}/{labelId}

Update label

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`labelId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	No	—
`color`	integer	No	—

Example:

json
{
  "name": "string",
  "color": 0
}

Responses

Code	Description
`200`	Label updated

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`label`	object	No	—

Response Example ( 200):

json
{
  "success": true,
  "label": {
    "id": "string",
    "name": "string",
    "color": 0,
    "predefinedId": "string"
  }
}

cURL Example

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

[DELETE] /labels/{sessionId}/{labelId}

Delete label

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`labelId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Label deleted

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/labels/session-01/label_01" \
  -H "X-API-Key: your-api-key"

[PUT] /labels/{id}

⚠️ DEPRECATED — DEPRECATED: Use PUT /labels/{sessionId}/{labelId} instead.

Update label (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`name`	string	No	—
`color`	integer	No	—

Example:

json
{
  "name": "string",
  "color": 0
}

Responses

Code	Description
`200`	Label updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/labels/abc123" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","color":0}'

[DELETE] /labels/{id}

⚠️ DEPRECATED — DEPRECATED: Use DELETE /labels/{sessionId}/{labelId} instead.

Delete label (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`id`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Label deleted

cURL Example

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

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

Get chat labels

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Responses

Code	Description
`200`	Chat labels

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`labels`	array of object	No	—

Response Example ( 200):

json
{
  "success": true,
  "labels": [
    {
      "id": "string",
      "name": "string",
      "color": 0,
      "predefinedId": "string"
    }
  ]
}

cURL Example

bash
curl -X GET "http://localhost:3000/api/labels/session-01/chat/628123456789@s.whatsapp.net/labels" \
  -H "X-API-Key: your-api-key"

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

Update chat labels

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`jid`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`labelIds`	array of string	✅ Yes	—
`action`	string	✅ Yes	Options: `add`, `remove`

Example:

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

Responses

Code	Description
`200`	Chat labels updated

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`labels`	array of object	No	—

Response Example ( 200):

json
{
  "success": true,
  "message": "string",
  "labels": [
    {
      "id": "string",
      "name": "string",
      "color": 0,
      "predefinedId": "string"
    }
  ]
}

cURL Example

bash
curl -X PUT "http://localhost:3000/api/labels/session-01/chat/628123456789@s.whatsapp.net/labels" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"labelIds":["string"],"action":"add"}'

[GET] /labels/chat-labels

⚠️ DEPRECATED — DEPRECATED: Use GET /labels/{sessionId}/chat/{jid}/labels instead.

Get chat labels (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	query	✅ Yes	string	—
`sessionId`	query	✅ Yes	string	—

Responses

Code	Description
`200`	Chat labels

cURL Example

bash
curl -X GET "http://localhost:3000/api/labels/chat-labels?jid=628123456789@s.whatsapp.net&sessionId=session-01" \
  -H "X-API-Key: your-api-key"

[PUT] /labels/chat-labels

⚠️ DEPRECATED — DEPRECATED: Use PUT /labels/{sessionId}/chat/{jid}/labels instead.

Add or remove labels from chat (DEPRECATED)

Parameters

Name	Located in	Required	Type	Description
`jid`	query	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`labelIds`	array of string	✅ Yes	—
`action`	string	✅ Yes	Options: `add`, `remove`

Example:

json
{
  "sessionId": "string",
  "labelIds": [
    "string"
  ],
  "action": "add"
}

Responses

Code	Description
`200`	Chat labels updated

cURL Example

bash
curl -X PUT "http://localhost:3000/api/labels/chat-labels?jid=628123456789@s.whatsapp.net" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","labelIds":["string"],"action":"add"}'

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

Get chats by label

Get all chats associated with a specific label

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—
`labelId`	path	✅ Yes	string	—

Responses

Code	Description
`200`	List of chats with label
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`404`	Label not found

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`label`	object	No	—
`chats`	array of string	No	—
`count`	integer	No	—

Response Example ( 200):

json
{
  "success": true,
  "label": {
    "text": "Hello from WA-AKG!"
  },
  "chats": [
    "string"
  ],
  "count": 0
}

cURL Example

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

📂 Notifications

[GET] /notifications

List notifications

Get the last 50 notifications for the authenticated user

Responses

Code	Description
`200`	List of notifications
`401`	Unauthorized - Invalid or missing API key
`500`	Error fetching notifications

Response Example ( 200):

json
[
  {
    "id": "string",
    "userId": "string",
    "title": "string",
    "message": "string",
    "type": "string",
    "href": "string",
    "read": true,
    "createdAt": "2026-01-15T08:00:00.000Z"
  }
]

cURL Example

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

[POST] /notifications

Create notification

Send a notification to a specific user or broadcast to all (Superadmin only)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`title`	string	✅ Yes	—
`message`	string	✅ Yes	—
`type`	string	No	Options: `INFO`, `SUCCESS`, `WARNING`, `ERROR` Default: `INFO`
`href`	string	No	—
`targetUserId`	string	No	Target user UUID
`broadcast`	boolean	No	Default: `false`

Example:

json
{
  "title": "Maintenance",
  "message": "System update in 5 minutes",
  "type": "INFO",
  "href": "/settings",
  "targetUserId": "string",
  "broadcast": true
}

Responses

Code	Description
`200`	Notification created
`400`	Invalid request
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Error creating notification

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`count`	integer	No	Number of users notified if broadcast

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/notifications" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Maintenance","message":"System update in 5 minutes","type":"INFO","href":"/settings","targetUserId":"string","broadcast":true}'

[PATCH] /notifications/read

Mark notifications as read

Mark specific or all notifications as read for the authenticated user

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`ids`	array of string	No	Array of notification IDs. If omitted or empty, all notifications are marked as read.

Example:

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

Responses

Code	Description
`200`	Notifications updated
`401`	Unauthorized - Invalid or missing API key
`500`	Error updating notifications

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

Response Example ( 200):

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

cURL Example

bash
curl -X PATCH "http://localhost:3000/api/notifications/read" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"]}'

[DELETE] /notifications/delete

Delete specific notification

Parameters

Name	Located in	Required	Type	Description
`id`	query	✅ Yes	string	Notification UUID

Responses

Code	Description
`200`	Notification deleted
`400`	Notification ID required
`401`	Unauthorized - Invalid or missing API key
`500`	Error deleting notification

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/notifications/delete?id=abc123" \
  -H "X-API-Key: your-api-key"

📂 System

[GET] /settings/system

Get system settings

Responses

Code	Description
`200`	System settings

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`appName`	string	No	—
`logoUrl`	string	No	—
`timezone`	string	No	—

Response Example ( 200):

json
{
  "id": "default",
  "appName": "WA-AKG",
  "logoUrl": "https://example.com/logo.png",
  "timezone": "Asia/Jakarta"
}

cURL Example

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

[POST] /settings/system

Update system settings

Update global system configuration (Superadmin/Owner only)

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`appName`	string	No	—
`logoUrl`	string	No	—
`timezone`	string	No	—

Example:

json
{
  "appName": "string",
  "logoUrl": "string",
  "timezone": "string"
}

Responses

Code	Description
`200`	Settings updated
`401`	Unauthorized - Invalid or missing API key
`500`	Failed to update settings

Response Fields ( 200):

Field	Type	Required	Description
`id`	string	No	—
`appName`	string	No	—
`logoUrl`	string	No	—
`timezone`	string	No	—
`updatedAt`	string (date-time)	No	—

Response Example ( 200):

json
{
  "id": "string",
  "appName": "string",
  "logoUrl": "string",
  "timezone": "string",
  "updatedAt": "2026-01-15T08:00:00.000Z"
}

cURL Example

bash
curl -X POST "http://localhost:3000/api/settings/system" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"appName":"string","logoUrl":"string","timezone":"string"}'

[POST] /status/{sessionId}/update

Update status

Post a status update (story) to WhatsApp. Supports text, image, and video.

Parameters

Name	Located in	Required	Type	Description
`sessionId`	path	✅ Yes	string	—

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`content`	string	✅ Yes	Status text or caption
`type`	string	No	Options: `TEXT`, `IMAGE`, `VIDEO` Default: `TEXT`
`mediaUrl`	string	No	Required for IMAGE and VIDEO
`backgroundColor`	integer	No	—
`font`	integer	No	—
`mentions`	array of string	No	—

Example:

json
{
  "content": "string",
  "type": "TEXT",
  "mediaUrl": "string",
  "backgroundColor": 0,
  "font": 0,
  "mentions": [
    "string"
  ]
}

Responses

Code	Description
`200`	Status posted
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`503`	Session not connected or ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/status/session-01/update" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"content":"string","type":"TEXT","mediaUrl":"string","backgroundColor":0,"font":0,"mentions":["string"]}'

[POST] /status/update

Update status

Post a status update (story) to WhatsApp. Supports text, image, and video.

Headers

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

Request Body ( `application/json`)

Field	Type	Required	Description
`sessionId`	string	✅ Yes	—
`content`	string	✅ Yes	Status text or caption
`type`	string	No	Options: `TEXT`, `IMAGE`, `VIDEO` Default: `TEXT`
`mediaUrl`	string	No	Required for IMAGE and VIDEO
`backgroundColor`	integer	No	ARGB color for TEXT status
`font`	integer	No	Font style for TEXT status
`mentions`	array of string	No	List of JIDs to mention/tag in the status

Example:

json
{
  "sessionId": "string",
  "content": "string",
  "type": "TEXT",
  "mediaUrl": "string",
  "backgroundColor": 0,
  "font": 0,
  "mentions": [
    "string"
  ]
}

Responses

Code	Description
`200`	Status updated
`400`	Missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied
`500`	Failed to post status
`503`	Session not ready

Response Fields ( 200):

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

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/status/update" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"string","content":"string","type":"TEXT","mediaUrl":"string","backgroundColor":0,"font":0,"mentions":["string"]}'

[POST] /system/check-updates

Check for updates

Checks for new releases on GitHub and creates a system notification if a newer version is available.

Responses

Code	Description
`200`	Check results
`401`	Unauthorized - Invalid or missing API key
`500`	Error checking updates

Response Fields ( 200):

Field	Type	Required	Description
`success`	boolean	No	—
`message`	string	No	—
`version`	string	No	Latest version tag

Response Example ( 200):

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

cURL Example

bash
curl -X POST "http://localhost:3000/api/system/check-updates" \
  -H "X-API-Key: your-api-key"

📦 Schemas

Error

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`error`	string	No	—

Example:

json
{
  "status": false,
  "message": "Error occurred",
  "error": "Detailed error info"
}

Success

Field	Type	Required	Description
`status`	boolean	No	—
`message`	string	No	—
`data`	object, nullable	No	—

Example:

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

Session

Field	Type	Required	Description
`id`	string	No	—
`name`	string	No	—
`sessionId`	string	No	—
`status`	string	No	Options: `Connected`, `Disconnected`, `Connecting`
`userId`	string	No	—
`botConfig`	object, nullable	No	—
`webhooks`	array of object	No	—
`_count`	object, nullable	No	—
`createdAt`	string (date-time)	No	—
`updatedAt`	string (date-time)	No	—

Example:

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"
}

Message

Field	Type	Required	Description
`text`	string	No	—

Example:

json
{
  "text": "Hello! How can I help you?"
}

Contact

Field	Type	Required	Description
`jid`	string	No	—
`name`	string	No	—
`notify`	string	No	—
`profilePic`	string, nullable	No	—

Example:

json
{
  "jid": "628123456789@s.whatsapp.net",
  "name": "John Doe",
  "notify": "string",
  "profilePic": "string"
}

ScheduledMessage

Field	Type	Required	Description
`id`	string	No	—
`sessionId`	string	No	—
`jid`	string	No	—
`content`	string	No	—
`sendAt`	string (date-time)	No	—
`status`	string	No	—

Example:

json
{
  "id": "string",
  "sessionId": "string",
  "jid": "string",
  "content": "string",
  "sendAt": "2026-01-15T08:00:00.000Z",
  "status": "PENDING"
}

Webhook

Field	Type	Required	Description
`id`	string	No	—
`sessionId`	string	No	—
`url`	string	No	—
`events`	array of string	No	—
`secret`	string	No	—

Example:

json
{
  "id": "string",
  "sessionId": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "secret": "string"
}

Group

Field	Type	Required	Description
`id`	string	No	—
`subject`	string	No	—
`desc`	string	No	—
`owner`	string	No	—
`size`	number	No	—
`participants`	array of object	No	—

Example:

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

Label

Field	Type	Required	Description
`id`	string	No	—
`name`	string	No	—
`color`	number, nullable	No	—
`predefinedId`	string, nullable	No	—

Example:

json
{
  "id": "string",
  "name": "string",
  "color": 0,
  "predefinedId": "string"
}

GroupDetails

Field	Type	Required	Description
`id`	string	No	—
`subject`	string	No	—
`subjectOwner`	string	No	—
`subjectTime`	number	No	—
`desc`	string	No	—
`descOwner`	string	No	—
`descId`	string	No	—
`owner`	string	No	—

Example:

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

WA-AKG API Documentation

WhatsApp AI Gateway — Complete API Reference

🔐 Authentication

📋 Common Parameters

📂 Web Authentication

[GET] /auth/session

Responses

cURL Example

[GET] /auth/csrf

Responses

cURL Example

📂 Sessions

[GET] /sessions

Responses

cURL Example

[POST] /sessions

Headers

Request Body ( application/json)

Responses

cURL Example

[GET] /sessions/{id}/qr

Parameters

Responses

cURL Example

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

Parameters

Responses

cURL Example

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

Parameters

Headers

Request Body ( application/json)

Responses

cURL Example

[GET] /sessions/{id}

Parameters

Responses

cURL Example

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

Parameters

Responses

cURL Example

[PATCH] /sessions/{id}/settings

Parameters

Headers

Request Body ( application/json)

Responses

cURL Example

[DELETE] /sessions/{id}/settings

Parameters

Responses

cURL Example

📂 Messaging (Deprecated)

[POST] /chat/send

Headers

Request Body ( application/json)

Responses

cURL Example

[POST] /chat/{sessionId}/send

Parameters

Headers

Request Body ( application/json)

Responses

cURL Example

📂 Messaging

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

Parameters

Headers

Request Body ( application/json)

Responses

cURL Example

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

Parameters

Headers

Request Body ( multipart/form-data)

Responses

cURL Example

[POST] /messages/{sessionId}/broadcast

Parameters

Headers

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `multipart/form-data`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)

Request Body ( `application/json`)