← Tất cả bài viết
Hướng dẫn

Xóa thành viên khỏi nhóm WhatsApp qua API: ID và xác minh kết quả

Để xóa một thành viên hiện tại khỏi nhóm WhatsApp qua UnifyPort, gửi POST /v1/accounts/{account_id}/groups/members với group_id, action: "remove" và LID của thành viên trong member_id. Lấy LID từ peer_id do danh sách thành viên trả về. Mỗi yêu cầu chỉ nhắm đến một người. Lưu phản hồi rồi đọc lại danh sách; một dòng biến mất khỏi giao diện không phải bằng chứng rằng thành viên đã bị xóa.

Điểm chính

  • Xóa thành viên, gỡ quyền quản trị, từ chối yêu cầu tham gia và để tài khoản kết nối tự rời nhóm là những thao tác khác nhau.
  • Chọn đồng thời tài khoản nhắn tin, nhóm và thành viên. Không tạo LID từ số điện thoại.
  • Cần xem xét và xác nhận quyết định xóa, không tự động xóa chỉ vì tên hiển thị lạ.
  • Hết thời gian chờ có nghĩa là chưa rõ kết quả, không phải được phép gửi lệnh xóa liên tục.

Chọn thao tác theo đúng mục đích

Hướng dẫn quản lý thành viên chính thức của WhatsApp mô tả việc chọn một người cụ thể trong thông tin nhóm rồi xác nhận xóa. Giao diện dùng API cũng nên giữ bước chọn đối tượng và xác nhận rõ ràng, thay vì giấu thao tác có tác động lớn sau nút chung chung như “Dọn dẹp”.

Mục đíchThao tác phù hợp
Xóa người đang là thành viênThao tác quản lý thành viên remove
Giữ người đó trong nhóm nhưng gỡ quyền quản trịThao tác riêng demote
Từ chối người chưa vào nhómTừ chối yêu cầu đang chờ
Để tài khoản kết nối rời nhómRời nhóm
Chỉ ẩn một dòng trong ứng dụng của bạnThay đổi giao diện cục bộ, không thay đổi thành viên

Để gỡ quyền, xem hướng dẫn thay đổi vai trò quản trị. Với người chưa tham gia, dùng hàng đợi duyệt yêu cầu vào nhóm. Các luồng này không nên dùng chung một nút “Xóa” có ý nghĩa mơ hồ.

Màn hình xác nhận cần hiển thị gì?

Trước khi bật thao tác xóa, gọi Liệt kê thành viên hội thoại trong tài khoản đã chọn, truyền ID nhóm vào conversation_id và đặt type=group. Tiếp tục phân trang theo data.has_more và data.next_cursor cho đến khi hoàn tất việc kiểm tra cần thiết. Không thấy một người ở trang đầu không có nghĩa là người đó không ở trong nhóm.

Giữ lại peer_id, display_name và role được trả về. Các vai trò trong tài liệu là member, admin và superadmin; vai trò cuối là chủ sở hữu hoặc người tạo nhóm. Tên hiển thị giúp người vận hành nhận ra đối tượng, nhưng không phải mã định danh để gửi lệnh.

Sau đây là biện pháp bảo vệ được đề xuất cho ứng dụng, không phải yêu cầu API bổ sung:

  • Hiển thị tài khoản kết nối, nhóm cụ thể và thành viên cùng lúc trước khi xác nhận.
  • Kiểm tra quyền của người vận hành trong ứng dụng và quyền quản lý nhóm của tài khoản kết nối. Có API Key không đồng nghĩa với có quyền quản trị nhóm.
  • Loại superadmin, chính tài khoản kết nối và đối tượng chưa xác minh danh tính khỏi luồng xóa thành viên thông thường; chuyển sang xem xét riêng hoặc thao tác thích hợp.
  • Đọc lại dữ liệu lựa chọn đã cũ và chặn các yêu cầu xóa đồng thời cho cùng tài khoản, nhóm và thành viên ở phía máy chủ.

Nếu chưa đối chiếu được mục tiêu với WhatsApp LID được trả về, hãy dừng lại. Không thay bằng số điện thoại, tên hiển thị hoặc ID người tham gia có định dạng khác từ sự kiện.

Một thành viên đã xác nhận, một yêu cầu

Tài liệu Quản lý thành viên nhóm nhận member_id đơn lẻ, không phải mảng member_ids dùng để quyết định các yêu cầu tham gia. UnifyPort cung cấp giao diện không chính thức. Bảng hỗ trợ thao tác theo nhà cung cấp hiện chỉ áp dụng thao tác này cho whatsapp, không áp dụng cho LINE, Telegram hay whatsapp-protocol. Không suy rộng khả năng này sang Zalo chỉ vì ứng dụng dùng chung giao diện quản lý.

Ví dụ JavaScript sau chỉ tạo nội dung yêu cầu. Truyền ID nhóm đã xác nhận và bản ghi được chọn từ danh sách thành viên. Đoạn mã không kiểm tra quyền và không gửi yêu cầu mạng.

function removalBody(groupId, selectedMember) {
  if (!groupId || !/^\d+@lid$/.test(selectedMember?.peer_id ?? '')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  if (!['member', 'admin'].includes(selectedMember.role)) {
    throw new Error('This target requires separate review');
  }
  return {
    group_id: groupId,
    action: 'remove',
    member_id: selectedMember.peer_id
  };
}

Điều kiện vai trò là chính sách an toàn cục bộ. Kiểm tra định dạng LID không chứng minh danh tính hay quyền hạn. Gửi JSON từ máy chủ đến endpoint nêu trên với X-Api-Key và Content-Type: application/json; không đưa khóa vào trình duyệt hoặc nhật ký. Tài liệu không định nghĩa giao dịch xóa nhiều người cùng lúc: dù giao diện cho phép chọn hàng loạt, hãy theo dõi kết quả riêng cho từng người đã được duyệt.

Đánh giá bằng chứng, không dựa vào hiệu ứng giao diện

Tách biệt ý định của người vận hành, kết quả HTTP và trạng thái thành viên quan sát được:

Bằng chứngĐiều ứng dụng có thể thông báo
200 OK với data.ok: trueAPI đã trả về thành công; cần làm mới danh sách thành viên
Đọc danh sách thành công, hoàn tất và không thấy LID đã chọnKhông quan sát thấy người đó trong lần đọc này; ghi lại thời điểm
Đọc danh sách thất bại hoặc chưa hoàn tấtViệc xác minh vẫn chưa được giải quyết
Yêu cầu thay đổi hết thời gian chờ hoặc phản hồi không đọc đượcChưa rõ kết quả; kiểm tra trước khi ghi tiếp

Sự kiện group.updated được tài liệu mô tả có thể chứa kind: "member_removed" cùng members[] trong data.changes[]. Dùng nó làm tín hiệu đối chiếu lại trạng thái, không coi là biên nhận riêng cho từng yêu cầu được đảm bảo sẽ đến. Xác minh chữ ký theo quy tắc phân phối webhook trước khi tin sự kiện. ID người tham gia trong sự kiện cũng chưa chắc dùng trực tiếp được cho yêu cầu quản lý thành viên tiếp theo.

Lưu request_id nếu có để chẩn đoán, nhưng không dùng nó làm khóa chống thực thi trùng lặp. Khi kết quả chưa rõ, đọc thành viên hiện tại và yêu cầu xem xét lại trước một thay đổi khác. Tự động gửi add để bù lại là quyết định mới về tư cách thành viên, không phải cơ chế hoàn tác được bảo đảm.

Câu hỏi thường gặp

Có dùng số điện thoại từ yêu cầu tạo nhóm được không?

Không. Thao tác này yêu cầu WhatsApp LID từ peer_id trong danh sách thành viên. Thành viên ban đầu khi tạo nhóm dùng quy tắc định danh khác.

Xóa thành viên có đồng thời xóa tin nhắn đã lưu hoặc cấm tham gia lại vĩnh viễn không?

Không nên cam kết những điều đó dựa trên API này. Phạm vi của nó là quản lý thành viên, không phải xóa lịch sử hoặc chính sách chặn tham gia vĩnh viễn. Hãy xử lý riêng việc lưu giữ dữ liệu và quyết định tiếp nhận trong tương lai.

Cần thử nghiệm gì trước khi bật tính năng?

Dùng tài khoản do bạn kiểm soát để thử tên trùng nhau, mục tiêu nằm ở trang sau, lựa chọn đã cũ, thiếu quyền, mất phản hồi và lỗi đọc lại để xác minh. Đây là đề xuất kiểm thử, không phải kết quả đã thực hiện.

Bước tiếp theo và nguồn tham khảo

Trước tiên xây dựng bước chọn và xác nhận dựa trên Liệt kê thành viên hội thoại, sau đó kết nối nút xóa với Quản lý thành viên nhóm.

Nguồn được đối chiếu ngày 2026-11-01:

UnifyPort API

Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.

Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.

Lấy API KeyXem tham chiếu API