Tài liệu API Zalo Server

🔐 Xác thực API

Hệ thống hỗ trợ 2 phương thức xác thực:

📋 Cách sử dụng API Key:

# Sử dụng header (khuyến nghị)
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/accounts

# Hoặc sử dụng query parameter
curl "http://localhost:3000/api/accounts?api_key=zalo_your_api_key_here"

💡 Lưu ý: API key có format zalo_ + 64 ký tự hex. Liên hệ admin để được cấp API key.

Mục lục

📋 APIs Quản lý Tài khoản

  1. accounts - Lấy danh sách tài khoản
  2. accountDetails - Chi tiết tài khoản
  3. zalo-accounts - Lấy danh sách tài khoản Zalo (API Key)
  4. zalo-accounts/:ownId - Chi tiết tài khoản Zalo (API Key)

🔍 Tìm kiếm & Thông tin

  1. findUserByAccount
  2. getUserInfoByAccount

💬 Gửi tin nhắn & Media

  1. sendMessageByAccount
  2. sendImageByAccount
  3. sendImageToUserByAccount
  4. sendImagesToUserByAccount
  5. sendImageToGroupByAccount
  6. sendImagesToGroupByAccount
  7. sendStickerByAccount
  8. sendVideoByAccount
  9. sendVoiceByAccount
  10. sendCardByAccount
  11. uploadAttachmentByAccount
  12. deleteMessageByAccount
  13. addReactionByAccount
  14. undoByAccount

👥 Quản lý nhóm

  1. createGroupByAccount
  2. getGroupInfoByAccount
  3. addUserToGroupByAccount
  4. removeUserFromGroupByAccount
  5. changeGroupAvatarByAccount
  6. changeGroupNameByAccount
  7. changeGroupOwnerByAccount
  8. addGroupDeputyByAccount
  9. removeGroupDeputyByAccount
  10. disperseGroupByAccount
  11. getGroupMembersInfoByAccount
  12. getGroupMembersByAccount
  13. joinGroupByAccount

👫 Quản lý bạn bè

  1. sendFriendRequestByAccount
  2. acceptFriendRequestByAccount
  3. changeFriendAliasByAccount
  4. blockUserByAccount
  5. unblockUserByAccount
  6. getAllFriendsByAccount
  7. blockViewFeedByAccount

⚙️ Quản lý tài khoản & Tiện ích

  1. updateProfileByAccount
  2. setSettingsAccountByAccount
  3. getQRByAccount
  4. getCookieByAccount
  5. getContextByAccount
  6. keepAliveByAccount
  7. parseLinkByAccount
  8. pinConversationsByAccount
  9. sendReportByAccount
  10. customByAccount

📡 Sự kiện

  1. sendSeenEventByAccount
  2. sendDeliveredEventByAccount
  3. sendTypingEventByAccount

⚠️ APIs Cũ (Cần ownId)

  1. findUser
  2. getUserInfo
  3. sendFriendRequest
  4. sendMessage
  5. createGroup
  6. getGroupInfo
  7. addUserToGroup
  8. removeUserFromGroup
  9. sendImageToUser
  10. sendImagesToUser
  11. sendImageToGroup
  12. sendImagesToGroup

📋 APIs Quản lý Tài khoản

1. accounts - Lấy danh sách tài khoản

Mục đích: Lấy danh sách tất cả tài khoản Zalo đã đăng nhập.

Endpoint: GET /api/accounts

Parameters: Không có

Response:

{
  "success": true,
  "data": [
    {
      "ownId": "123456789",
      "phoneNumber": "0901234567",
      "proxy": "http://proxy1:8080",
      "displayName": "0901234567 (123456789)",
      "isOnline": true
    }
  ],
  "total": 1
}

Ví dụ curl:

# Với API key (khuyến nghị)
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/accounts

# Hoặc với query parameter
curl "http://localhost:3000/api/accounts?api_key=zalo_your_api_key_here"

# Không có API key (cần đăng nhập session)
curl http://localhost:3000/api/accounts

2. accountDetails - Chi tiết tài khoản

Mục đích: Lấy thông tin chi tiết của một tài khoản cụ thể.

Endpoint: GET /api/accounts/:ownId

Parameters:

Field Loại Mô tả Bắt buộc
ownId string (URL param) ID tài khoản Zalo cần lấy thông tin. Có

Response:

{
  "success": true,
  "data": {
    "ownId": "123456789",
    "phoneNumber": "0901234567",
    "proxy": "http://proxy1:8080",
    "profile": {
      "displayName": "Tên hiển thị",
      "avatar": "avatar_url"
    },
    "isOnline": true
  }
}

Ví dụ curl:

# Với API key (khuyến nghị)
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/accounts/123456789

# Hoặc với query parameter
curl "http://localhost:3000/api/accounts/123456789?api_key=zalo_your_api_key_here"

# Không có API key (cần đăng nhập session)
curl http://localhost:3000/api/accounts/123456789

3. zalo-accounts - Lấy danh sách tài khoản Zalo (API Key)

Mục đích: Lấy danh sách tài khoản Zalo đã đăng nhập (qua QR code). Đây là endpoint yêu cầu API key với quyền zalo:account_management.

Endpoint: GET /api/zalo-accounts

Permission: zalo:account_management

Parameters: Không có

Response:

{
  "success": true,
  "data": [
    {
      "ownId": "123456789",
      "phoneNumber": "0901234567",
      "proxy": "http://proxy1:8080",
      "displayName": "0901234567 (123456789)",
      "isOnline": true
    }
  ],
  "total": 1
}

Ví dụ curl:

# Với API key (bắt buộc)
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/zalo-accounts

# Hoặc với query parameter
curl "http://localhost:3000/api/zalo-accounts?api_key=zalo_your_api_key_here"

💡 So sánh với /api/accounts:

4. zalo-accounts/:ownId - Chi tiết tài khoản Zalo (API Key)

Mục đích: Lấy thông tin chi tiết một tài khoản Zalo cụ thể. Yêu cầu API key.

Endpoint: GET /api/zalo-accounts/:ownId

Permission: zalo:account_management

Parameters:

Field Loại Mô tả Bắt buộc
ownId string (URL param) ID tài khoản Zalo cần lấy thông tin. Có

Response:

{
  "success": true,
  "data": {
    "ownId": "123456789",
    "phoneNumber": "0901234567",
    "proxy": "http://proxy1:8080",
    "profile": {
      "displayName": "Tên hiển thị",
      "avatar": "avatar_url"
    },
    "isOnline": true
  }
}

Ví dụ curl:

# Với API key (bắt buộc)
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/zalo-accounts/123456789

# Hoặc với query parameter
curl "http://localhost:3000/api/zalo-accounts/123456789?api_key=zalo_your_api_key_here"

🔥 APIs N8N-Friendly (Khuyến nghị sử dụng)

Lưu ý: Các APIs này sử dụng accountSelection thay vì ownId, giúp dễ dàng sử dụng từ n8n workflows.

3. findUserByAccount

Mục đích: Tìm kiếm người dùng dựa trên số điện thoại với account selection.

Endpoint: POST /api/findUserByAccount

Parameters:

Field Loại Mô tả Bắt buộc
phone string Số điện thoại của người dùng cần tìm. Có
accountSelection string Số điện thoại hoặc ownId của tài khoản để thực hiện tìm kiếm. Có

Response:

{
  "success": true,
  "data": { /* Kết quả tìm kiếm */ },
  "usedAccount": {
    "ownId": "123456789",
    "phoneNumber": "0901234567"
  }
}

Ví dụ:

{
  "phone": "0987654321",
  "accountSelection": "0901234567"
}

Ví dụ curl:

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "phone": "0987654321",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/findUserByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "phone": "0987654321",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/findUserByAccount?api_key=zalo_your_api_key_here"

# Không có API key (cần đăng nhập session)
curl -X POST -H "Content-Type: application/json" -d '{
  "phone": "0987654321",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/findUserByAccount

4. sendMessageByAccount

Mục đích: Gửi tin nhắn với account selection.

Endpoint: POST /api/sendMessageByAccount

Parameters:

Field Loại Mô tả Bắt buộc
message string Nội dung tin nhắn Có
threadId string ID người dùng/nhóm Có
type string "user" hoặc "group" Không
accountSelection string Số điện thoại hoặc ownId Có

Ví dụ:

{
  "message": "Hello from n8n!",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}

Ví dụ curl:

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "message": "Hello from n8n!",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendMessageByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "message": "Hello from n8n!",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendMessageByAccount?api_key=zalo_your_api_key_here"

# Không có API key (cần đăng nhập session)
curl -X POST -H "Content-Type: application/json" -d '{
  "message": "Hello from n8n!",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendMessageByAccount

5. sendImageByAccount

Mục đích: Gửi hình ảnh với account selection.

Endpoint: POST /api/sendImageByAccount

Parameters:

Field Loại Mô tả Bắt buộc
imagePath string URL hình ảnh Có
threadId string ID người dùng/nhóm Có
type string "user" hoặc "group" Không
accountSelection string Số điện thoại hoặc ownId Có

Ví dụ:

{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}

Ví dụ curl:

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImageByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendImageByAccount?api_key=zalo_your_api_key_here"

# Không có API key (cần đăng nhập session)
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_thread_id",
  "type": "user",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImageByAccount

📝 Các APIs khác với *ByAccount - Ví dụ curl

getUserInfoByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "userId": "user_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/getUserInfoByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "userId": "user_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/getUserInfoByAccount?api_key=zalo_your_api_key_here"

sendFriendRequestByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "userId": "user_id_here",
  "message": "Xin chào, hãy kết bạn với tôi!",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendFriendRequestByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "userId": "user_id_here",
  "message": "Xin chào, hãy kết bạn với tôi!",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendFriendRequestByAccount?api_key=zalo_your_api_key_here"

createGroupByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "members": ["user_id_1", "user_id_2"],
  "name": "Tên nhóm mới",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/createGroupByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "members": ["user_id_1", "user_id_2"],
  "name": "Tên nhóm mới",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/createGroupByAccount?api_key=zalo_your_api_key_here"

getGroupInfoByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "groupId": "group_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/getGroupInfoByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "group_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/getGroupInfoByAccount?api_key=zalo_your_api_key_here"

addUserToGroupByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "groupId": "group_id_here",
  "memberId": "user_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/addUserToGroupByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "group_id_here",
  "memberId": "user_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/addUserToGroupByAccount?api_key=zalo_your_api_key_here"

removeUserFromGroupByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "groupId": "group_id_here",
  "memberId": "user_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/removeUserFromGroupByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "group_id_here",
  "memberId": "user_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/removeUserFromGroupByAccount?api_key=zalo_your_api_key_here"

sendImageToUserByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImageToUserByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "user_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendImageToUserByAccount?api_key=zalo_your_api_key_here"

sendImagesToUserByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePaths": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
  "threadId": "user_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImagesToUserByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePaths": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
  "threadId": "user_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendImagesToUserByAccount?api_key=zalo_your_api_key_here"

sendImageToGroupByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "group_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImageToGroupByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePath": "https://example.com/image.jpg",
  "threadId": "group_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendImageToGroupByAccount?api_key=zalo_your_api_key_here"

sendImagesToGroupByAccount

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePaths": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
  "threadId": "group_id_here",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/sendImagesToGroupByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "imagePaths": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
  "threadId": "group_id_here",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/sendImagesToGroupByAccount?api_key=zalo_your_api_key_here"

getGroupMembersByAccount

🆕 Quét thông tin thành viên nhóm Zalo

# Với API key (khuyến nghị)
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "groupUrl": "https://zalo.me/g/your_group_id",
  "accountSelection": "0901234567"
}' http://localhost:3000/api/getGroupMembersByAccount

# Hoặc với query parameter
curl -X POST -H "Content-Type: application/json" -d '{
  "groupUrl": "https://zalo.me/g/your_group_id",
  "accountSelection": "0901234567"
}' "http://localhost:3000/api/getGroupMembersByAccount?api_key=zalo_your_api_key_here"

📋 Response mẫu:

{
  "success": true,
  "data": {
    "groupInfo": {
      "groupId": "your_group_id",
      "name": "Tên nhóm",
      "description": "Mô tả nhóm",
      "avatar": "https://avatar-url.jpg",
      "totalMembers": 25,
      "createdTime": 1640995200000,
      "creatorId": "creator_user_id"
    },
    "members": [
      {
        "userId": "user_id_1",
        "displayName": "Nguyễn Văn A",
        "phoneNumber": "0901234567",
        "avatar": "https://avatar-url.jpg",
        "role": "admin",
        "isActive": true,
        "lastActiveTime": 1640995200000,
        "joinTime": null,
        "gender": 1,
        "status": "Đang hoạt động"
      }
    ],
    "summary": {
      "totalMembers": 25,
      "admins": 3,
      "activeMembers": 20,
      "membersWithPhone": 15,
      "scannedAt": "2024-01-01T10:00:00.000Z"
    }
  },
  "usedAccount": {
    "ownId": "your_account_id",
    "phoneNumber": "0901234567"
  }
}

⚠️ Lưu ý quan trọng:

🔥 Ưu điểm của APIs *ByAccount:

📋 Workflow n8n mẫu:

1. Gọi GET /api/accounts để lấy danh sách tài khoản
2. Tạo dropdown từ field "displayName" hoặc "phoneNumber"
3. Sử dụng APIs *ByAccount với accountSelection
4. Kiểm tra usedAccount trong response để xác nhận

🚀 Quick Test Commands

Test cơ bản với curl (sử dụng API key):

# 1. Lấy danh sách tài khoản
curl -H "X-API-Key: zalo_your_api_key_here" http://localhost:3000/api/accounts

# 2. Gửi tin nhắn test
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "message": "Test message from API",
  "threadId": "YOUR_THREAD_ID",
  "accountSelection": "YOUR_PHONE_NUMBER"
}' http://localhost:3000/api/sendMessageByAccount

# 3. Tìm user
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "phone": "TARGET_PHONE_NUMBER",
  "accountSelection": "YOUR_PHONE_NUMBER"
}' http://localhost:3000/api/findUserByAccount

# 4. Gửi hình ảnh
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "imagePath": "https://example.com/test-image.jpg",
  "threadId": "YOUR_THREAD_ID",
  "accountSelection": "YOUR_PHONE_NUMBER"
}' http://localhost:3000/api/sendImageByAccount

# 5. Quét thành viên nhóm
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: zalo_your_api_key_here" -d '{
  "groupUrl": "https://zalo.me/g/YOUR_GROUP_ID",
  "accountSelection": "YOUR_PHONE_NUMBER"
}' http://localhost:3000/api/getGroupMembersByAccount

💡 Lưu ý khi test:

👥 Quản lý nhóm nâng cao

changeGroupAvatarByAccount

Endpoint: POST /api/changeGroupAvatarByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
avatarPath string Đường dẫn/URL ảnh avatar mới Có
accountSelection string SĐT hoặc ownId Có

changeGroupNameByAccount

Endpoint: POST /api/changeGroupNameByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
name string Tên nhóm mới Có
accountSelection string SĐT hoặc ownId Có

changeGroupOwnerByAccount

Endpoint: POST /api/changeGroupOwnerByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
newOwnerId string ID thành viên sẽ làm chủ nhóm mới Có
accountSelection string SĐT hoặc ownId Có

addGroupDeputyByAccount

Endpoint: POST /api/addGroupDeputyByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
memberId string ID thành viên được bổ nhiệm phó nhóm Có
accountSelection string SĐT hoặc ownId Có

removeGroupDeputyByAccount

Endpoint: POST /api/removeGroupDeputyByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
memberId string ID phó nhóm cần xóa Có
accountSelection string SĐT hoặc ownId Có

disperseGroupByAccount

Endpoint: POST /api/disperseGroupByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm cần giải tán Có
accountSelection string SĐT hoặc ownId Có

getGroupMembersInfoByAccount

Endpoint: POST /api/getGroupMembersInfoByAccount

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupId string ID nhóm Có
accountSelection string SĐT hoặc ownId Có

joinGroupByAccount

Endpoint: POST /api/zalo/join-group-by-account

Permission: zalo:group_management

Field Loại Mô tả Bắt buộc
groupUrl string URL nhóm Zalo (https://zalo.me/g/...) Có
accountSelection string SĐT hoặc ownId Có

👫 Quản lý bạn bè

acceptFriendRequestByAccount

Endpoint: POST /api/acceptFriendRequestByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
userId string ID người gửi lời mời Có
accountSelection string SĐT hoặc ownId Có

changeFriendAliasByAccount

Endpoint: POST /api/changeFriendAliasByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
userId string ID bạn bè Có
alias string Biệt danh mới Có
accountSelection string SĐT hoặc ownId Có

blockUserByAccount

Endpoint: POST /api/blockUserByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
userId string ID người dùng cần chặn Có
accountSelection string SĐT hoặc ownId Có

unblockUserByAccount

Endpoint: POST /api/unblockUserByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
userId string ID người dùng cần bỏ chặn Có
accountSelection string SĐT hoặc ownId Có

getAllFriendsByAccount

Endpoint: POST /api/getAllFriendsByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có

blockViewFeedByAccount

Endpoint: POST /api/blockViewFeedByAccount

Permission: zalo:friend_management

Field Loại Mô tả Bắt buộc
userId string ID người dùng cần chặn xem feed Có
accountSelection string SĐT hoặc ownId Có

⚙️ Quản lý tài khoản & Tiện ích

updateProfileByAccount

Endpoint: POST /api/updateProfileByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
... object Các trường profile cần cập nhật Có

setSettingsAccountByAccount

Endpoint: POST /api/setSettingsAccountByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
... object Các cài đặt cần thay đổi Có

getQRByAccount

Endpoint: POST /api/getQRByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có

getCookieByAccount

Endpoint: POST /api/getCookieByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có

getContextByAccount

Endpoint: POST /api/getContextByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có

keepAliveByAccount

Endpoint: POST /api/keepAliveByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có

parseLinkByAccount

Endpoint: POST /api/parseLinkByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
link string URL cần parse Có

pinConversationsByAccount

Endpoint: POST /api/pinConversationsByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
conversationId string ID cuộc hội thoại Có

sendReportByAccount

Endpoint: POST /api/sendReportByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
... object Nội dung báo cáo Có

customByAccount

Endpoint: POST /api/customByAccount

Permission: zalo:account_management

Field Loại Mô tả Bắt buộc
accountSelection string SĐT hoặc ownId Có
... object Params tùy chỉnh Tùy

💬 Tin nhắn & Media nâng cao

sendStickerByAccount

Endpoint: POST /api/sendStickerByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
stickerId string ID sticker Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

sendVideoByAccount

Endpoint: POST /api/sendVideoByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
videoUrl string URL video Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

sendVoiceByAccount

Endpoint: POST /api/sendVoiceByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
voiceUrl string URL file âm thanh Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

sendCardByAccount

Endpoint: POST /api/sendCardByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
cardUserId string ID user trong card Có
threadId string ID người nhận Có
accountSelection string SĐT hoặc ownId Có

uploadAttachmentByAccount

Endpoint: POST /api/uploadAttachmentByAccount

Permission: zalo:send_image

Field Loại Mô tả Bắt buộc
filePath string URL file đính kèm Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

deleteMessageByAccount

Endpoint: POST /api/deleteMessageByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
messageId string ID tin nhắn cần xóa Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

addReactionByAccount

Endpoint: POST /api/addReactionByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
messageId string ID tin nhắn Có
reaction string Emoji reaction Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

undoByAccount

Endpoint: POST /api/undoByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
messageId string ID tin nhắn cần thu hồi Có
threadId string ID người dùng/nhóm Có
accountSelection string SĐT hoặc ownId Có

📡 Sự kiện

sendSeenEventByAccount

Endpoint: POST /api/sendSeenEventByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
threadId string ID cuộc hội thoại Có
accountSelection string SĐT hoặc ownId Có

sendDeliveredEventByAccount

Endpoint: POST /api/sendDeliveredEventByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
threadId string ID cuộc hội thoại Có
accountSelection string SĐT hoặc ownId Có

sendTypingEventByAccount

Endpoint: POST /api/sendTypingEventByAccount

Permission: zalo:send_message

Field Loại Mô tả Bắt buộc
threadId string ID cuộc hội thoại Có
accountSelection string SĐT hoặc ownId Có

🔒 Quyền API Key (Permissions)

Mỗi API key được gán quyền cụ thể. Nếu chọn "Tất cả quyền", key có thể truy cập mọi API.

Quyền Mô tả APIs liên quan
* Tất cả quyền Toàn bộ APIs
zalo:find_user Tìm kiếm người dùng findUser*, getUserInfo*
zalo:send_message Gửi tin nhắn sendMessage*, sendSticker*, sendVideo*, sendVoice*, sendCard*, deleteMessage*, addReaction*, undo*, sendSeen/Delivered/Typing*
zalo:send_image Gửi hình ảnh sendImage*, sendImages*, uploadAttachment*
zalo:group_management Quản lý nhóm createGroup*, getGroupInfo*, addUser/removeUser*, changeGroup*, Deputy*, disperseGroup*, getGroupMembers*, joinGroup*
zalo:friend_management Quản lý bạn bè sendFriendRequest*, acceptFriendRequest*, changeFriendAlias*, block/unblock*, getAllFriends*, blockViewFeed*
zalo:account_management Quản lý tài khoản accounts, updateProfile*, setSettings*, getQR*, getCookie*, getContext*, keepAlive*, parseLink*, pinConversations*, custom*

⚠️ APIs Cũ (Cần ownId)

Lưu ý: Các APIs này vẫn hoạt động nhưng khuyến nghị sử dụng APIs *ByAccount ở trên.

16. findUser (API cũ)

Mục đích: Tìm kiếm người dùng dựa trên số điện thoại.

Endpoint: POST /api/findUser

Parameters:

Field Loại Mô tả Bắt buộc
phone string Số điện thoại của người dùng. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "phone": "0123456789",
  "ownId": "0000000000000000001"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "phone": "0123456789",
  "ownId": "0000000000000000001"
}' http://localhost:3000/api/findUser

2. getUserInfo

Mục đích: Lấy thông tin chi tiết của một người dùng.

Endpoint: POST /api/getUserInfo

Parameters:

Field Loại Mô tả Bắt buộc
userId string ID của người dùng cần lấy thông tin. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "userId": "0000000000000000001",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "userId": "0000000000000000001",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/getUserInfo

3. sendFriendRequest

Mục đích: Gửi lời mời kết bạn đến người dùng.

Endpoint: POST /api/sendFriendRequest

Parameters:

Field Loại Mô tả Bắt buộc
userId string ID của người dùng nhận lời mời. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "userId": "0000000000000000002",
  "ownId": "0000000000000000001"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "userId": "0000000000000000002",
  "ownId": "0000000000000000001"
}' http://localhost:3000/api/sendFriendRequest

4. sendMessage

Mục đích: Gửi tin nhắn văn bản (hoặc object) đến người dùng hoặc nhóm.

Endpoint: POST /api/sendmessage

Parameters:

Field Loại Mô tả Bắt buộc
message string | Object Nội dung tin nhắn (có thể là string hoặc object MessageContent). Có
threadId string ID của người dùng/nhóm để gửi tin. Có
type number Loại thread (0: User hoặc 1: Group). Mặc định là 0. Không
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "message": "Xin chào",
  "threadId": "0000000000000000001",
  "type": 0,
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "message": "Xin chào",
  "threadId": "0000000000000000001",
  "type": 0,
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/sendmessage

5. createGroup

Mục đích: Tạo một nhóm mới.

Endpoint: POST /api/createGroup

Parameters:

Field Loại Mô tả Bắt buộc
members string[] Mảng ID các thành viên (không bao gồm bản thân). Có
name string Tên của nhóm. Không
avatarPath string Đường dẫn ảnh nhóm (nếu có). Không
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "members": ["0000000000000000002", "0000000000000000003"],
  "name": "Nhóm Mới",
  "avatarPath": "./avatar.jpg",
  "ownId": "0000000000000000001"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "members": ["0000000000000000002", "0000000000000000003"],
  "name": "Nhóm Mới",
  "avatarPath": "./avatar.jpg",
  "ownId": "0000000000000000001"
}' http://localhost:3000/api/createGroup

6. getGroupInfo

Mục đích: Lấy thông tin chi tiết của các nhóm.

Endpoint: POST /api/getGroupInfo

Parameters:

Field Loại Mô tả Bắt buộc
groupId string | string[] ID của nhóm hoặc mảng các ID. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "groupId": "0000000000000000000",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "0000000000000000000",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/getGroupInfo

7. addUserToGroup

Mục đích: Thêm thành viên vào nhóm.

Endpoint: POST /api/addUserToGroup

Parameters:

Field Loại Mô tả Bắt buộc
groupId string ID của nhóm. Có
memberId string | string[] ID của thành viên (hoặc mảng ID) cần thêm vào nhóm. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "groupId": "0000000000000000000",
  "memberId": ["0000000000000000001", "0000000000000000002"],
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "0000000000000000000",
  "memberId": ["0000000000000000001", "0000000000000000002"],
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/addUserToGroup

8. removeUserFromGroup

Mục đích: Xóa thành viên khỏi nhóm.

Endpoint: POST /api/removeUserFromGroup

Parameters:

Field Loại Mô tả Bắt buộc
groupId string ID của nhóm. Có
memberId string | string[] ID của thành viên (hoặc mảng ID) cần xóa khỏi nhóm. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "groupId": "0000000000000000000",
  "memberId": ["0000000000000000001", "0000000000000000002"],
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "groupId": "0000000000000000000",
  "memberId": ["0000000000000000001", "0000000000000000002"],
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/removeUserFromGroup

9. sendImageToUser

Mục đích: Gửi một hình ảnh đến người dùng.

Endpoint: POST /api/sendImageToUser

Parameters:

Field Loại Mô tả Bắt buộc
imagePath string Đường dẫn hoặc URL đến hình ảnh cần gửi (gửi trong request body dưới tên imageUrl). Có
threadId string ID của người dùng nhận tin nhắn. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "imageUrl": "./path/to/image.jpg",
  "threadId": "0000000000000000001",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "imageUrl": "./path/to/image.jpg",
  "threadId": "0000000000000000001",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/sendImageToUser

10. sendImagesToUser

Mục đích: Gửi nhiều hình ảnh đến người dùng.

Endpoint: POST /api/sendImagesToUser

Parameters:

Field Loại Mô tả Bắt buộc
imagePaths string[] Mảng đường dẫn hoặc URL hình ảnh (gửi trong request body dưới tên imageUrls). Có
threadId string ID của người dùng nhận tin nhắn. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "imageUrls": ["./path/to/image1.jpg", "./path/to/image2.jpg"],
  "threadId": "0000000000000000001",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "imageUrls": ["./path/to/image1.jpg", "./path/to/image2.jpg"],
  "threadId": "0000000000000000001",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/sendImagesToUser

11. sendImageToGroup

Mục đích: Gửi một hình ảnh đến nhóm.

Endpoint: POST /api/sendImageToGroup

Parameters:

Field Loại Mô tả Bắt buộc
imagePath string Đường dẫn hoặc URL đến hình ảnh cần gửi (gửi trong request body dưới tên imageUrl). Có
threadId string ID của nhóm nhận tin nhắn. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "imagePath": "./path/to/group-image.jpg",
  "threadId": "0000000000000000000",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "imageUrl": "./path/to/group-image.jpg",
  "threadId": "0000000000000000000",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/sendImageToGroup

12. sendImagesToGroup

Mục đích: Gửi nhiều hình ảnh đến nhóm.

Endpoint: POST /api/sendImagesToGroup

Parameters:

Field Loại Mô tả Bắt buộc
imagePaths string[] Mảng đường dẫn hoặc URL hình ảnh (gửi trong request body dưới tên imageUrls). Có
threadId string ID của nhóm nhận tin nhắn. Có
ownId string ID tài khoản Zalo đang đăng nhập (lấy từ /accounts). Có

Ví dụ:

{
  "imageUrls": ["./path/to/group-image1.jpg", "./path/to/group-image2.jpg"],
  "threadId": "0000000000000000000",
  "ownId": "0000000000000000009"
}

Ví dụ curl:

curl -X POST -H "Content-Type: application/json" -d '{
  "imageUrls": ["./path/to/group-image1.jpg", "./path/to/group-image2.jpg"],
  "threadId": "0000000000000000000",
  "ownId": "0000000000000000009"
}' http://localhost:3000/api/sendImagesToGroup