Hướng dẫn October 17, 2026

Đổi quản trị viên nhóm WhatsApp qua API: promote và demote

Để đổi quản trị viên nhóm WhatsApp qua UnifyPort, gọi POST /v1/accounts/{account_id}/groups/members với group_id, LID của thành viên trong member_id và action: "promote" hoặc "demote". Mỗi lần gọi xử lý một thành viên và một thao tác. Gỡ quyền quản trị viên không phải thao tác remove để xóa thành viên khỏi nhóm. Hãy đọc trạng thái thành viên hiện tại trước và loại người tạo nhóm khỏi quy trình hạ quyền thông thường.

Điểm chính

Chọn đồng thời tài khoản nhắn tin, nhóm và thành viên; tên hiển thị không phải mã định danh.
Dùng LID được trả về trong peer_id của danh sách thành viên, không tự tạo từ số điện thoại.
Phân biệt member, admin và superadmin trước khi bật nút đổi vai trò.
Đọc lại trạng thái sau yêu cầu; không tự gửi thao tác ngược lại khi hết thời gian chờ.

Xác định rõ thay đổi vai trò

Hướng dẫn chính thức về quản trị viên của WhatsApp mô tả cách gỡ quyền quản trị và nêu rằng không thể xóa người tạo nhóm; họ vẫn là quản trị viên trừ khi tự rời nhóm. Tích hợp API không thay đổi quy tắc này.

Bảng dưới đây là chính sách đề xuất cho ứng dụng, không phải cam kết nền tảng sẽ chấp nhận mọi yêu cầu:

Vai trò quan sát được	Ý định của người vận hành	Cách ứng dụng xử lý
`member`	Bổ nhiệm làm quản trị viên	Cho phép chọn `promote` sau khi kiểm tra quyền
`admin`	Giữ tư cách thành viên, gỡ quyền quản trị	Cho phép chọn `demote` sau xác nhận
`superadmin`	Gỡ quyền của người tạo nhóm	Dừng quy trình và giải thích giới hạn
Đã có vai trò mong muốn	Lặp lại cùng thay đổi	Làm mới giao diện thay vì gửi lại
Thiếu, không rõ hoặc chưa đủ dữ liệu thành viên	Vẫn đổi vai trò	Đọc lại hoặc kiểm tra thủ công

Đây không phải quy trình duyệt vào nhóm. Để quyết định ai được tham gia, dùng hàng đợi duyệt yêu cầu vào nhóm WhatsApp. Để chia sẻ lời mời, dùng quy trình liên kết mời nhóm riêng. Cả hai đều không bổ nhiệm quản trị viên.

Lưu lựa chọn từ danh sách thành viên hiện tại

Gọi Danh sách thành viên cuộc trò chuyện dưới tài khoản đã chọn. Truyền conversation_id của nhóm, phân trang bằng cursor và lưu peer_id cùng role của mục đã chọn. Các vai trò được tài liệu định nghĩa là member, admin, superadmin; giá trị cuối chỉ chủ sở hữu hoặc người tạo nhóm.

Ví dụ yêu cầu đọc dưới đây dùng biến môi trường do backend điền từ lựa chọn thực tế:

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

Nếu data.has_more là true, tiếp tục bằng data.next_cursor được trả về. Không thấy một người ở trang đầu không chứng minh họ đã rời nhóm. Giữ nguyên LID; không suy ra từ số điện thoại, tên hiển thị hay ID người tham gia có định dạng khác trong sự kiện.

Trước khi gửi, kiểm tra người vận hành có quyền quản lý tài khoản và nhóm này, đồng thời tài khoản WhatsApp đã kết nối có quyền cần thiết trong nhóm. Quyền truy cập API của workspace không tự cấp quyền quản trị nhóm. Giữ API Key ở máy chủ.

Gửi một thay đổi rõ ràng mỗi lần

Tài liệu quản lý thành viên nhóm định nghĩa bốn thao tác: add, remove, promote, demote. Khi đổi vai trò, chỉ dùng hai thao tác cuối với trường số ít member_id, không dùng mảng member_ids của quy trình duyệt yêu cầu vào nhóm.

Đoạn JavaScript minh họa này chỉ tạo phần thân yêu cầu từ bản ghi thành viên đã chọn. Nó không kiểm tra phân quyền và không gửi yêu cầu mạng:

function roleChangeBody(groupId, selectedMember, action) {
  const expectedRole = { promote: 'member', demote: 'admin' };
  if (!Object.hasOwn(expectedRole, action) ||
      selectedMember?.role !== expectedRole[action]) {
    throw new Error('Refresh membership before changing this role');
  }
  if (!groupId || !selectedMember?.peer_id?.endsWith('@lid')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  return {
    group_id: groupId,
    member_id: selectedMember.peer_id,
    action
  };
}

Gửi JSON từ backend đến endpoint được tài liệu mô tả với X-Api-Key. Kiểm tra hậu tố chỉ là biện pháp ngăn lỗi cục bộ, không chứng minh danh tính hay quyền hạn. Màn hình xác nhận phải hiển thị rõ nhóm, thành viên và thao tác. Đừng suy ra đối tượng từ hàng đang đứng đầu trong danh sách liên tục cập nhật.

UnifyPort cung cấp giao diện không chính thức cho tài khoản đã kết nối. Ma trận hỗ trợ thao tác theo kênh hiện chỉ ánh xạ thao tác ghi này tới whatsapp, không gồm LINE, Telegram, Zalo hay nhà cung cấp riêng whatsapp-protocol. Khả năng đọc thành viên hoặc nhận sự kiện nhóm trên một kênh khác không có nghĩa là có thể đổi vai trò qua endpoint này.

Kiểm tra kết quả, không giả định có giao dịch nguyên tử

Tài liệu mô tả phản hồi thành công là 200 OK với data.ok: true. Lưu kết quả HTTP và request_id, sau đó đọc lại thành viên để hiển thị vai trò quan sát được riêng với ý định của người vận hành.

Các biện pháp đề xuất:

Tuần tự hóa thay đổi trong ứng dụng đối với cùng tài khoản, nhóm và thành viên.
Kiểm tra lại vai trò ngay trước khi gửi; quản trị viên khác có thể đã đổi vai trò sau lúc mở hộp thoại.
Khi hết thời gian chờ, đánh dấu kết quả chưa xác định và kiểm tra danh sách hiện tại. Không tự gửi lại hay thực hiện thao tác ngược để bù trừ.
Không coi việc bàn giao giữa nhiều người là một giao dịch nguyên tử. Hãy xác nhận vai trò thực tế của quản trị viên mới trước, rồi mới xem xét gỡ quyền người cũ bằng thao tác riêng.

Sự kiện chuẩn group.updated có thể chứa các mục trong data.changes[] với kind: "promoted" hoặc "demoted" và members[]. Có thể dùng nó để kích hoạt đối soát trạng thái, nhưng không coi đó là biên nhận được bảo đảm cho từng yêu cầu. ID người tham gia trong sự kiện không mặc nhiên là LID hợp lệ cho lần ghi tiếp theo. Khi xử lý webhook, làm theo tài liệu chữ ký và phân phối, xác minh trước khi tin cậy nội dung, đồng thời xử lý sự kiện trùng hoặc đến sai thứ tự.

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

demote có xóa thành viên khỏi nhóm không?

Không. Gỡ vai trò và xóa thành viên là hai thao tác riêng. Không gắn nút “Gỡ quyền quản trị viên” với remove.

Có thể đổi vai trò của người tạo nhóm không?

Không nên cung cấp thao tác đó trong quy trình này. WhatsApp nêu rằng người tạo vẫn là quản trị viên cho đến khi tự rời nhóm; danh sách UnifyPort biểu diễn vai trò này bằng superadmin.

Có thể đổi nhiều quản trị viên trong một yêu cầu không?

Endpoint này không hỗ trợ. Mỗi lần nhận một member_id và một thao tác. Nếu ứng dụng xử lý hàng loạt, phải theo dõi riêng kết quả từng mục.

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

Bắt đầu với Danh sách thành viên cuộc trò chuyện, rồi thêm nút đổi vai trò theo Quản lý thành viên nhóm. Trước khi bật trong môi trường thực tế, kiểm thử phân trang, chọn người tạo nhóm, vai trò đã cũ, thiếu quyền và kết quả mạng chưa rõ. Đây là danh sách kiểm thử đề xuất, không phải kết quả đã chạy.

Nguồn được kiểm tra ngày 2026-10-17:

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 Key Xem tham chiếu API