Zalo API RESTful Server

RESTful API server sử dụng thư viện zca-js để tích hợp với Zalo Web.

🚀 Cài đặt

Clone repository:

git clone <repository-url>
cd ZaloAPI2Restful

Cài đặt dependencies:

npm install

Sao chép file cấu hình:

cp env.example .env

Cấu hình file .env với thông tin của bạn.

🏃‍♂️ Chạy server

# Development mode
npm run dev

# Production mode  
npm start

Server sẽ chạy tại http://localhost:3000

📋 API Documentation

🔐 Authentication

Đăng nhập bằng QR Code

POST /api/auth/qr

Response:

{
    "success": true,
    "message": "Đăng nhập thành công",
    "credentials": {
        "imei": "device_imei",
        "userAgent": "Mozilla/5.0...",
        "cookies": "base64_encoded_cookies"
    }
}

Kiểm tra trạng thái đăng nhập

GET /api/auth/status

Response:

{
    "connected": true,
    "message": "Đã kết nối"
}

💬 Messages

Gửi tin nhắn

POST /api/messages/send

Request Body:

{
    "message": "Nội dung tin nhắn",
    "threadId": "user_id_or_group_id",
    "threadType": 1
}

Thread Types:

1 = Tin nhắn cá nhân (User)
2 = Tin nhắn nhóm (Group)

Response:

{
    "success": true,
    "data": "Message sent successfully"
}

Tìm sticker

GET /api/messages/stickers/:keyword

Parameters:

keyword (string): Từ khóa tìm kiếm sticker

Response:

{
    "success": true,
    "data": [
        {
            "id": "sticker_id",
            "name": "Sticker name",
            "url": "sticker_url"
        }
    ]
}

👤 Users

Thông tin tài khoản

GET /api/users/me

Response:

{
    "success": true,
    "data": {
        "id": "user_id",
        "name": "User Name",
        "avatar": "avatar_url"
    }
}

Danh sách bạn bè

GET /api/users/friends

Response:

{
    "success": true,
    "data": [
        {
            "id": "friend_id",
            "name": "Friend Name",
            "avatar": "avatar_url"
        }
    ]
}

🤖 Bot Commands

Xử lý lệnh bot

POST /api/bot/command

Request Body:

{
    "message": "/ping",
    "threadId": "user_id_or_group_id",
    "threadType": 1
}

Response:

{
    "success": true,
    "data": {
        "command": "ping",
        "response": "🏓 Pong! Bot đang hoạt động bình thường.",
        "sent": true
    }
}

Auto-reply bot

POST /api/bot/auto-reply

Request Body:

{
    "message": "Xin chào bot",
    "threadId": "user_id_or_group_id", 
    "threadType": 1
}

Response:

{
    "success": true,
    "data": {
        "originalMessage": "Xin chào bot",
        "response": "🤖 Bot đã nhận tin nhắn: \"Xin chào bot\"\n\nGõ /help để xem danh sách lệnh bot.",
        "sent": true
    }
}

Danh sách lệnh bot có sẵn:

/ping - Kiểm tra bot hoạt động
/time - Xem thời gian hiện tại
/help - Hiển thị danh sách lệnh
/info - Thông tin bot
/weather [tên thành phố] - Xem thời tiết (gọi API bên ngoài)
/joke - Kể chuyện cười
/quote - Câu nói hay
/api - Gọi API bên ngoài (demo)
/news - Tin tức mới nhất (gọi API bên ngoài)
/translate [văn bản] - Dịch thuật (gọi API bên ngoài)

🔗 Webhook Integration

Khởi động webhook listener

POST /api/webhook/start-listener

Response:

{
    "success": true,
    "message": "Webhook listener đã được khởi động. Bot sẽ tự động phản hồi tin nhắn."
}

Dừng webhook listener

POST /api/webhook/stop-listener

Response:

{
    "success": true,
    "message": "Webhook listener đã được dừng."
}

Webhook nhận tin nhắn

POST /api/webhook/message

Request Body:

{
    "message": "/weather Hà Nội",
    "threadId": "user_id_or_group_id",
    "threadType": 1,
    "senderId": "sender_user_id"
}

Response:

{
    "success": true,
    "data": {
        "originalMessage": "/weather Hà Nội",
        "response": "🌤️ Thời tiết tại Hà Nội: Nắng đẹp, nhiệt độ 25°C",
        "senderId": "sender_user_id",
        "sent": true
    }
}

👥 Groups

Danh sách nhóm

GET /api/groups

Response:

{
    "success": true,
    "data": [
        {
            "id": "group_id",
            "name": "Group Name",
            "avatar": "group_avatar_url",
            "memberCount": 10
        }
    ]
}

Thông tin nhóm

GET /api/groups/:groupId

Parameters:

groupId (string): ID của nhóm

Response:

{
    "success": true,
    "data": {
        "id": "group_id",
        "name": "Group Name",
        "avatar": "group_avatar_url",
        "memberCount": 10,
        "members": [
            {
                "id": "member_id",
                "name": "Member Name",
                "role": "admin"
            }
        ]
    }
}

🔧 Cấu hình Environment

File .env:

# Zalo API Configuration
ZALO_USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:133.0) Gecko/20100101 Firefox/133.0
ZALO_IMEI=
ZALO_LANGUAGE=vi

# Server Configuration
PORT=3000
NODE_ENV=development

# API Rate Limiting (Disabled for local use)
RATE_LIMIT_WINDOW_MS=0
RATE_LIMIT_MAX_REQUESTS=0

# Cookie Information (Base64 encoded JSON)
ZALO_COOKIES=

# Optional: QR Code Path for authentication
QR_CODE_PATH=./qr.png

# Optional: Self listen (true/false)
SELF_LISTEN=false

📝 Ví dụ sử dụng

Gửi tin nhắn cá nhân

curl -X POST http://localhost:3000/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Xin chào từ bot!",
    "threadId": "user_id_here",
    "threadType": 1
  }'

Gửi tin nhắn nhóm

curl -X POST http://localhost:3000/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thông báo nhóm",
    "threadId": "group_id_here",
    "threadType": 2
  }'

Lấy danh sách bạn bè

curl -X GET http://localhost:3000/api/users/friends

Gửi lệnh bot

# Gửi lệnh ping
curl -X POST http://localhost:3000/api/bot/command \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/ping",
    "threadId": "user_id_here",
    "threadType": 1
  }'

# Gửi lệnh thời tiết
curl -X POST http://localhost:3000/api/bot/command \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/weather Hà Nội",
    "threadId": "user_id_here",
    "threadType": 1
  }'

Auto-reply bot

# Bot tự động phản hồi
curl -X POST http://localhost:3000/api/bot/auto-reply \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Xin chào bot",
    "threadId": "user_id_here",
    "threadType": 1
  }'

Webhook Integration

# Khởi động webhook listener (bot tự động phản hồi)
curl -X POST http://localhost:3000/api/webhook/start-listener

# Dừng webhook listener
curl -X POST http://localhost:3000/api/webhook/stop-listener

# Gửi tin nhắn qua webhook
curl -X POST http://localhost:3000/api/webhook/message \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/weather Hà Nội",
    "threadId": "user_id_here",
    "threadType": 1,
    "senderId": "sender_id"
  }'

Lệnh bot với API bên ngoài

# Gọi API bên ngoài
curl -X POST http://localhost:3000/api/bot/command \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/api",
    "threadId": "user_id_here",
    "threadType": 1
  }'

# Dịch thuật
curl -X POST http://localhost:3000/api/bot/command \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/translate Hello world",
    "threadId": "user_id_here",
    "threadType": 1
  }'

# Tin tức
curl -X POST http://localhost:3000/api/bot/command \
  -H "Content-Type: application/json" \
  -d '{
    "message": "/news",
    "threadId": "user_id_here",
    "threadType": 1
  }'

⚠️ Lưu ý

Rate limiting đã được tắt cho môi trường local
Cần đăng nhập QR trước khi sử dụng các API khác
API này chỉ dành cho mục đích cá nhân, không nên sử dụng cho production
Sử dụng có thể dẫn đến khóa tài khoản Zalo

🛠️ Dependencies

zca-js - Zalo API library
express - Web framework
sharp - Image processing
axios - HTTP client for external APIs
cors - CORS middleware
helmet - Security headers
morgan - Logging
express-rate-limit - Rate limiting
dotenv - Environment variables

📄 License

MIT License

ZaloAPI2Restful

Install / Use

README

Zalo API RESTful Server

🚀 Cài đặt

🏃‍♂️ Chạy server

📋 API Documentation

🔐 Authentication

Đăng nhập bằng QR Code

Kiểm tra trạng thái đăng nhập

💬 Messages

Gửi tin nhắn

Tìm sticker

👤 Users

Thông tin tài khoản

Danh sách bạn bè

🤖 Bot Commands

Xử lý lệnh bot

Auto-reply bot

🔗 Webhook Integration

Khởi động webhook listener

Dừng webhook listener

Webhook nhận tin nhắn

👥 Groups

Danh sách nhóm

Thông tin nhóm

🔧 Cấu hình Environment

📝 Ví dụ sử dụng

Gửi tin nhắn cá nhân

Gửi tin nhắn nhóm

Lấy danh sách bạn bè

Gửi lệnh bot

Auto-reply bot

Webhook Integration

Lệnh bot với API bên ngoài

⚠️ Lưu ý

🛠️ Dependencies

📄 License