🤖 QR ChatBot API Documentation

Complete API reference for WhatsApp Web.js integration

v2.1.0

📖 Overview

The QR ChatBot API provides a comprehensive WhatsApp Web.js integration with modern REST endpoints. All API routes are prefixed with /api/ and return standardized JSON responses.

Base URL

http://localhost:7000/api/

Response Format

All API responses follow this standardized format:

{
  "success": boolean,
  "data": any,
  "message": string,
  "timestamp": string,
  "statusCode": number
}

Content Type

All requests should use Content-Type: application/json for POST requests.

🔐 Authentication

The API supports hybrid authentication: session-based for web interface and API key for programmatic access.

🔑 API Key Authentication

For API access, include your API key in the request header:

x-api-key: your_api_key_here

All /api/ endpoints (except /api/status) require API key authentication.

POST /auth
Authenticate user and create session
Parameter Type Required Description
username string Required Admin username
password string Required Admin password

Request Payload Example:

{
  "username": "admin",
  "password": "your_password"
}

Success Response:

302 Redirects to /home

Error Response:

401 Authentication Failed page
GET /authlogout
Destroy session and logout user

Response:

302 Redirects to /

⚙️ Client Management

GET /api/status
Get public server status (no authentication required)

Success Response:

200 
{
  "success": true,
  "data": {
    "status": "running",
    "version": "2.1.0",
    "uptime": 3600,
    "port": 7000,
    "whatsappReady": true,
    "timestamp": "2025-09-25T10:30:00.000Z"
  },
  "message": "Server status retrieved",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
GET /api/state
Get WhatsApp client state and information

Success Response:

200 
{
  "success": true,
  "data": {
    "state": "CONNECTED",
    "info": {
      "displayName": "User Name",
      "me": {
        "user": "6281234567890",
        "server": "c.us"
      }
    }
  },
  "message": "Client state retrieved",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
GET /api/destroy
Destroy WhatsApp client and clean up session files

Success Response:

200 
{
  "success": true,
  "data": null,
  "message": "WhatsApp client destroyed successfully",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
GET /api/logout
Logout from WhatsApp Web

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Logged out successfully",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}

👥 Contacts & Chats

🔒 Authentication required
GET /api/contacts
Get all contacts from WhatsApp

Success Response:

200 
{
  "success": true,
  "data": [
    {
      "id": {
        "user": "6281234567890",
        "server": "c.us"
      },
      "name": "Contact Name",
      "pushname": "Push Name",
      "isUser": true,
      "isGroup": false
    }
  ],
  "message": "Contacts retrieved successfully",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
GET /api/chats
Get all active chats

Success Response:

200 
{
  "success": true,
  "data": [
    {
      "id": {
        "user": "6281234567890",
        "server": "c.us"
      },
      "name": "Chat Name",
      "isGroup": false,
      "isReadOnly": false,
      "unreadCount": 0,
      "timestamp": 1726483800
    }
  ],
  "message": "Chats retrieved successfully",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/profile-pic
Get profile picture URL for a contact
Parameter Type Required Description
number string Required Phone number (will be formatted automatically)

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/..."
  },
  "message": "Profile picture URL retrieved",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/contact
Get contact information by phone number
Parameter Type Required Description
number string Required Phone number (will be formatted automatically)

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "user": "6281234567890",
      "server": "c.us"
    },
    "name": "Contact Name",
    "pushname": "Push Name",
    "isUser": true,
    "isGroup": false,
    "isBlocked": false
  },
  "message": "Contact information retrieved",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat-messages
Get messages from a specific chat
Parameter Type Required Description
number string Required Phone number
limit integer Optional Number of messages to retrieve (1-100, default: 20)

Request Payload Example:

{
  "number": "081234567890",
  "limit": 50
}

Success Response:

200 
{
  "success": true,
  "data": [
    {
      "id": {
        "fromMe": false,
        "remote": "6281234567890@c.us",
        "id": "ABC123DEF456",
        "_serialized": "false_6281234567890@c.us_ABC123DEF456"
      },
      "ack": 1,
      "hasMedia": false,
      "body": "Hello! How are you?",
      "type": "chat",
      "timestamp": 1726483800,
      "notifyName": "Contact Name",
      "from": "6281234567890@c.us",
      "to": "6280987654321@c.us"
    }
  ],
  "message": "Chat messages retrieved successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/search-messages
Search messages across all chats or specific chat
Parameter Type Required Description
query string Required Search query
chatId string Optional Specific chat ID to search in
limit integer Optional Number of results (1-100, default: 50)

Request Payload Example:

{
  "query": "hello world",
  "chatId": "6281234567890@c.us",
  "limit": 20
}

Success Response:

200 
{
  "success": true,
  "data": [
    {
      "id": {
        "fromMe": true,
        "remote": "6281234567890@c.us",
        "id": "ABC123DEF456",
        "_serialized": "true_6281234567890@c.us_ABC123DEF456"
      },
      "body": "Hello world! How are you today?",
      "type": "chat",
      "timestamp": 1726483800,
      "from": "6280987654321@c.us",
      "to": "6281234567890@c.us",
      "chat": {
        "id": "6281234567890@c.us",
        "name": "Contact Name"
      }
    }
  ],
  "message": "Messages found successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}

💬 Chat Management

🔒 Authentication required
POST /api/chat/archive
Archive a chat
Parameter Type Required Description
number string Required Phone number to archive

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat archived successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/unarchive
Unarchive a chat
Parameter Type Required Description
number string Required Phone number to unarchive

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat unarchived successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/mute
Mute a chat to stop receiving notifications
Parameter Type Required Description
number string Required Phone number to mute

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat muted successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/unmute
Unmute a chat to resume receiving notifications
Parameter Type Required Description
number string Required Phone number to unmute

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat unmuted successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/pin
Pin a chat to keep it at the top of the chat list
Parameter Type Required Description
number string Required Phone number to pin

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat pinned successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/unpin
Unpin a chat from the top of the chat list
Parameter Type Required Description
number string Required Phone number to unpin

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat unpinned successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/clear
Clear all messages from a chat (delete chat history)
Parameter Type Required Description
number string Required Phone number to clear messages

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": true,
  "message": "Chat messages cleared successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/chat/read
Mark a chat as read (sets unreadCount to 0)
Parameter Type Required Description
number string Required Phone number to mark as read

Request Payload Example:

{
  "number": "081234567890"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "chatId": "6281234567890@c.us",
    "previousUnreadCount": 5,
    "currentUnreadCount": 0,
    "isRead": true,
    "timestamp": "2025-10-04T10:30:00.000Z"
  },
  "message": "Chat marked as read successfully",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 200
}

🔍 Response Details:

  • chatId - Formatted phone number with WhatsApp domain
  • previousUnreadCount - Number of unread messages before marking as read
  • currentUnreadCount - Number of unread messages after marking as read (should be 0)
  • isRead - Boolean indicating if chat is now fully read
  • timestamp - When the read status was updated

📝 Chat Management Summary

All chat management endpoints require:

  • Authentication: Valid API key in the x-api-key header
  • Method: POST request
  • Content-Type: application/json
  • Phone number formatting: Numbers are automatically formatted (e.g., 081234567890 → 6281234567890@c.us)

Common Error Responses:

// Missing API Key (401)
{
  "success": false,
  "data": null,
  "message": "Authentication required. Please provide x-api-key header.",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 401
}

// Invalid API Key (403)
{
  "success": false,
  "data": null,
  "message": "Invalid API key provided.",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 403
}

// Validation Error (422)
{
  "success": false,
  "data": [
    {
      "field": "number",
      "message": "Phone number is required"
    }
  ],
  "message": "Validation failed",
  "timestamp": "2025-10-04T10:30:00.000Z",
  "statusCode": 422
}

📨 Messaging

🔒 Authentication required
POST /api/send-message
Send a text message to a contact
Parameter Type Required Description
number string Required Phone number (will be formatted automatically)
message string Required Message content 
{
  "number": "081234567890",
  "message": "Hello from QR ChatBot!"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "fromMe": true,
      "remote": "6281234567890@c.us",
      "id": "ABC123DEF456",
      "_serialized": "true_6281234567890@c.us_ABC123DEF456"
    },
    "ack": 1,
    "hasMedia": false,
    "body": "Hello from QR ChatBot!",
    "type": "chat",
    "timestamp": 1726483800
  },
  "message": "Message sent successfully",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/send-quoted-message
Send a message quoting another message
Parameter Type Required Description
number string Required Phone number
message string Required Message content
quotedMessageId string Required ID of the message to quote

Request Payload Example:

{
  "number": "081234567890",
  "message": "This is my reply to your message",
  "quotedMessageId": "false_6281234567890@c.us_ABC123DEF456"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "fromMe": true,
      "remote": "6281234567890@c.us",
      "id": "XYZ789ABC123",
      "_serialized": "true_6281234567890@c.us_XYZ789ABC123"
    },
    "ack": 1,
    "hasMedia": false,
    "body": "This is my reply to your message",
    "type": "chat",
    "timestamp": 1726483800,
    "hasQuotedMsg": true,
    "quotedMsg": {
      "id": "false_6281234567890@c.us_ABC123DEF456",
      "body": "Original quoted message content"
    }
  },
  "message": "Quoted message sent successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/send-media
Send media message (image, video, document, etc.)
Parameter Type Required Description
number string Required Phone number
base64 string Required Base64 encoded media data
mimetype string Required MIME type (e.g., image/jpeg, video/mp4)
filename string Optional Filename for the media
caption string Optional Caption for the media

Request Payload Example:

{
  "number": "081234567890",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
  "mimetype": "image/png",
  "filename": "image.png",
  "caption": "Hello, this is an image!"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "fromMe": true,
      "remote": "6281234567890@c.us",
      "id": "MEDIA123ABC456",
      "_serialized": "true_6281234567890@c.us_MEDIA123ABC456"
    },
    "ack": 1,
    "hasMedia": true,
    "body": "Hello, this is an image!",
    "type": "image",
    "timestamp": 1726483800,
    "mediaKey": "media_key_here",
    "size": 1024
  },
  "message": "Media message sent successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/send-group-message
Send message to a group
Parameter Type Required Description
id string Optional* Group ID (either id or name required)
name string Optional* Group name (either id or name required)
message string Required Message content

📝 Note

Either id or name must be provided. If name is used, the system will search for the group by name.

Request Payload Example (using group ID):

{
  "id": "120363042833171234@g.us",
  "message": "Hello everyone in the group!"
}

Request Payload Example (using group name):

{
  "name": "My WhatsApp Group",
  "message": "Hello everyone in the group!"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "fromMe": true,
      "remote": "120363042833171234@g.us",
      "id": "GROUP123ABC456",
      "_serialized": "true_120363042833171234@g.us_GROUP123ABC456"
    },
    "ack": 1,
    "hasMedia": false,
    "body": "Hello everyone in the group!",
    "type": "chat",
    "timestamp": 1726483800,
    "from": "6280987654321@c.us",
    "to": "120363042833171234@g.us"
  },
  "message": "Group message sent successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
POST /api/send-group-media
Send media message to a group
Parameter Type Required Description
id string Optional* Group ID (either id or name required)
name string Optional* Group name (either id or name required)
base64 string Required Base64 encoded media data
mimetype string Required MIME type (e.g., image/jpeg, video/mp4)
filename string Optional Filename for the media
caption string Optional Caption for the media

Request Payload Example (using group ID):

{
  "id": "120363042833171234@g.us",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
  "mimetype": "image/png",
  "filename": "group-image.png",
  "caption": "Sharing this image with the group!"
}

Request Payload Example (using group name):

{
  "name": "My WhatsApp Group",
  "base64": "/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "mimetype": "image/jpeg",
  "filename": "photo.jpg",
  "caption": "Check out this photo!"
}

Success Response:

200 
{
  "success": true,
  "data": {
    "id": {
      "fromMe": true,
      "remote": "120363042833171234@g.us",
      "id": "GROUPMEDIA123ABC456",
      "_serialized": "true_120363042833171234@g.us_GROUPMEDIA123ABC456"
    },
    "ack": 1,
    "hasMedia": true,
    "body": "Sharing this image with the group!",
    "type": "image",
    "timestamp": 1726483800,
    "from": "6280987654321@c.us",
    "to": "120363042833171234@g.us",
    "mediaKey": "group_media_key_here",
    "size": 2048
  },
  "message": "Group media message sent successfully",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 200
}
🔒 Authentication required
GET /api/media/:filename
Get a media file that was previously downloaded
Parameter Type Required Description
filename string Required Filename in URL path

URL Example:

GET /api/media/image_2025-09-25_10-30-00.jpg

Success Response:

200 Returns the media file with appropriate headers 
Content-Type: image/jpeg
Content-Disposition: inline; filename="image_2025-09-25_10-30-00.jpg"

[Binary file data]

Error Response:

404 
{
  "success": false,
  "data": null,
  "message": "Media file not found",
  "timestamp": "2025-09-25T10:30:00.000Z",
  "statusCode": 404
}
🔒 Authentication required
POST /api/download-file
Download a media file from a specific message using chat_id and message_id. The file will be saved to the downloaded-media folder and return download information.

📁 Public Media Access

Downloaded media files are accessible via two URLs:

  • Public URL: /media/filename.ext - No authentication required
  • API URL: /api/media/filename.ext - Requires API key authentication

The response includes both URLs for convenience. Use the public URL for direct browser access or embedding.

Parameter Type Required Description
chat_id string Required WhatsApp chat ID (e.g., "6281234567890@c.us" for individual, "1234567890-1234567890@g.us" for group)
message_id string Required Message ID that contains media. Can be full format (e.g., "false_6281234567890@c.us_3EB0123456789ABCDEF") or just the ID part (e.g., "3EB0123456789ABCDEF")

Request Example:

curl -X POST http://localhost:7000/api/download-file \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "chat_id": "6281234567890@c.us",
    "message_id": "3EB0123456789ABCDEF"
  }'

Success Response:

200 
{
  "success": true,
  "data": {
    "filename": "3EB0123456789ABCDEF.jpg",
    "original_message_id": "false_6281234567890@c.us_3EB0123456789ABCDEF",
    "mimetype": "image/jpeg",
    "filesize": 245760,
    "download_url": "http://localhost:7000/media/3EB0123456789ABCDEF.jpg",
    "api_download_url": "http://localhost:7000/api/media/3EB0123456789ABCDEF.jpg",
    "saved_path": "./downloaded-media/3EB0123456789ABCDEF.jpg",
    "chat_id": "6281234567890@c.us",
    "message_id": "false_6281234567890@c.us_3EB0123456789ABCDEF"
  },
  "message": "File downloaded successfully",
  "timestamp": "2025-09-28T10:30:00.000Z",
  "statusCode": 200
}

Error Responses:

404 - Chat Not Found 
{
  "success": false,
  "data": null,
  "message": "Chat not found",
  "timestamp": "2025-09-28T10:30:00.000Z",
  "statusCode": 404
}
404 - Message Not Found 
{
  "success": false,
  "data": null,
  "message": "Message not found",
  "timestamp": "2025-09-28T10:30:00.000Z",
  "statusCode": 404
}
400 - No Media 
{
  "success": false,
  "data": null,
  "message": "Message does not contain media",
  "timestamp": "2025-09-28T10:30:00.000Z",
  "statusCode": 400
}
GET /media/:filename
🌍 Public Access - No Authentication Required
Access downloaded media files directly without authentication. Perfect for sharing or embedding files.
Parameter Type Required Description
filename string Required Filename in URL path (e.g., "3EB0123456789ABCDEF.pdf")

URL Examples:

GET /media/false_6281320223846@c.us_3EB091C14A7158427C5BE5.pdf
GET /media/3EB091C14A7158427C5BE5.pdf
GET /media/image_2025-09-28_10-30-00.jpg

Success Response:

200 Returns the media file with appropriate headers 
Content-Type: application/pdf
Content-Disposition: inline; filename="document.pdf"

[Binary file data]

Error Response:

404 
Cannot GET /media/nonexistent-file.pdf

🔄 Legacy Routes

For backward compatibility, old API endpoints are still supported but deprecated. They will redirect to new endpoints.

⚠️ Deprecation Notice

Legacy routes are deprecated and may be removed in future versions. Please update your applications to use the new /api/ endpoints.

Legacy Route New Route Status
/logout /api/logout Deprecated
/state /api/state Deprecated
/contact /api/contacts Deprecated
/getchatactive /api/chats Deprecated
/send-message /api/send-message Deprecated
/send-media64 /api/send-media Deprecated

💡 Usage Examples

Here are some practical examples of using the API with cURL commands:

Send Text Message

curl -X POST http://localhost:7000/api/send-message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "number": "081234567890",
    "message": "Hello from API!"
  }'

Send Media Message

curl -X POST http://localhost:7000/api/send-media \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "number": "081234567890",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
    "mimetype": "image/png",
    "filename": "test.png",
    "caption": "Test image via API"
  }'

Get Contacts

curl -X GET http://localhost:7000/api/contacts \
  -H "x-api-key: your_api_key_here"

Get Chat Messages

curl -X POST http://localhost:7000/api/chat-messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "number": "081234567890",
    "limit": 20
  }'

Send Group Message

curl -X POST http://localhost:7000/api/send-group-message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "name": "My WhatsApp Group",
    "message": "Hello group members!"
  }'

📝 Tips for API Usage

  • Always include the x-api-key header for authentication
  • Use Content-Type: application/json for POST requests
  • Phone numbers will be automatically formatted (add country code if missing)
  • Base64 encode media files before sending
  • Check response status codes for error handling

❌ Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code Meaning Description
200 OK Request succeeded
400 Bad Request The request was invalid
401 Unauthorized Authentication required
404 Not Found Resource not found
500 Internal Server Error Server error occurred

Error Response Format

{
  "success": false,
  "data": null,
  "message": "Error description",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 400
}

Validation Errors

When input validation fails, the API returns a 422 status code with detailed error information:

{
  "success": false,
  "data": [
    {
      "field": "number",
      "message": "Phone number is required"
    },
    {
      "field": "message",
      "message": "Message content is required"
    }
  ],
  "message": "Validation failed",
  "timestamp": "2025-09-16T10:30:00.000Z",
  "statusCode": 422
}

Common Error Messages

📞 Support

For support or questions about this API, please check:

🔧 Development Mode

This documentation is for the QR ChatBot API v2.1.0. Make sure your application is running on the correct port and that WhatsApp Web is properly authenticated.