Hướng dẫn November 9, 2026

Đồng bộ danh sách thành viên nhóm WhatsApp bằng group.updated

Để cập nhật danh sách thành viên nhóm WhatsApp trong ứng dụng, hãy dùng webhook group.updated của UnifyPort làm tín hiệu tải lại qua List conversation members. Xử lý mọi phần tử trong data.changes[], nhưng không coi các ID người tham gia trong đó là toàn bộ danh sách. Chỉ công bố danh sách mới sau khi đọc thành công tất cả các trang. Nếu có thay đổi đến trong lúc đọc, hãy lên lịch đọc thêm một lượt.

Điểm chính

data.actor là người thực hiện thay đổi; changes[].members[] là những người chịu tác động.
Tư cách thành viên và vai trò quản trị viên là hai khía cạnh khác nhau.
Kết quả chưa đầy đủ hoặc lỗi đọc không được xóa danh sách đã quan sát trước đó.
Đây là đồng bộ phía đọc, không phải tự động quản lý thành viên.

Đọc thông báo, đừng biến nó thành lệnh

Tài liệu quản trị viên của WhatsApp phân biệt việc bổ nhiệm và gỡ vai trò quản trị. Giao diện danh sách cũng cần giữ sự phân biệt này: thay đổi vai trò không có nghĩa là rời nhóm.

Tài liệu group.updated của UnifyPort định nghĩa data.conversation, data.actor và data.changes[]. Một sự kiện có thể chứa nhiều thay đổi. Xác định nhóm bằng ngữ cảnh workspace của bên nhận, provider, account_id và data.conversation.id, không dùng tên nhóm.

Loại thay đổi	Tác động tới danh sách	Cách xử lý đề xuất
`member_added` / `member_removed`	Thành viên có thể đã thay đổi	Yêu cầu tải lại danh sách
`promoted` / `demoted`	Vai trò có thể đã thay đổi	Đọc lại cả định danh và vai trò
`renamed` / `description_changed` / `avatar_changed`	Thông tin nhóm thay đổi	Chuyển sang luồng làm mới thông tin nhóm riêng
`dissolved`	Vòng đời nhóm thay đổi	Đánh dấu cần kiểm tra, không tự xóa lịch sử đã lưu

Duyệt toàn bộ mảng, không chỉ changes[0]. Nếu cùng sự kiện có cả đổi tên và thêm thành viên, phải kích hoạt cả hai loại cập nhật liên quan. Giữ lại phần tử không nhận diện được hoặc sai cấu trúc để điều tra thay vì đoán tác động.

Nếu nhân viên thực sự cần đổi vai trò, hãy dùng quy trình bổ nhiệm và gỡ quản trị viên riêng. Thông báo một người bị xóa khỏi nhóm không nên tạo thêm yêu cầu xóa. Thao tác ghi có chủ đích thuộc quy trình xóa thành viên.

Dựng danh sách từ lượt đọc hoàn tất

List conversation members trả về peer_id, display_name, avatar_url và role. Các vai trò 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 backend dưới đây dùng biến môi trường chứa định danh tài khoản nhắn tin và nhóm được chọn thực tế. Bài viết chưa chạy yêu cầu này:

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, truyền data.next_cursor vào tham số query cursor của yêu cầu tiếp theo. Gom toàn bộ trang vào tập dữ liệu tạm, dùng peer_id được trả về làm khóa. Giữ API key ở backend.

Không xóa một người khỏi giao diện chỉ vì họ không nằm ở trang đầu. Nếu bất kỳ trang nào lỗi, giữ danh sách từ lượt đọc hoàn tất gần nhất và hiển thị rằng lần làm mới chưa hoàn thành. Đọc đầy đủ thành công nhưng không có thành viên khác với yêu cầu thất bại.

Giữ nguyên định danh. ID người tham gia trong sự kiện không nhất thiết thay thế được peer_id trong danh sách. Đặc biệt, endpoint quản lý thành viên WhatsApp yêu cầu LID thành viên được trả về. Không tạo LID từ số điện thoại hoặc sửa chuỗi để coi hai ID khác định dạng là cùng một người.

Không để lượt làm mới làm mất tín hiệu tiếp theo

Sau đây là thuật toán ứng dụng được đề xuất, không phải trường bổ sung của UnifyPort hay bảo đảm giao dịch phía máy chủ:

Tiếp nhận sự kiện vào bộ lưu trữ bền vững. Đăng ký group.updated và giữ các đăng ký cần thiết khác. Kiểm tra chữ ký cùng dấu thời gian theo quy định giao webhook trước khi tin nội dung. Chữ ký là HMAC-SHA256 dạng hex, dùng signing_secret trên X-Device-Timestamp, một dấu chấm và phần thân nguyên gốc.
Ghi nhu cầu làm mới một cách nguyên tử. Trong cùng một giao dịch, lưu sự kiện thông thường đã xác thực với cơ chế khử trùng theo event ID, đồng thời tăng số thế hệ làm mới cục bộ của nhóm. Sau đó mới trả 2xx. Lần giao lặp không được tạo thêm thao tác nghiệp vụ.
Mỗi nhóm trong cùng phạm vi chỉ có một worker đọc. Ghi lại thế hệ cục bộ hiện tại, rồi tải đủ các trang thành viên. Có thể gộp nhiều sự kiện chờ thành một lượt đọc, thay vì truy vấn cho từng người tham gia.
Kiểm tra lại trước khi công bố. Trong giao dịch phối hợp với luồng tiếp nhận, so sánh thế hệ lúc bắt đầu với hiện tại. Nếu đã thay đổi trong khi phân trang, coi kết quả tạm là quan sát sơ bộ và lên lịch lượt mới. Đừng đánh dấu danh sách đã cập nhật xong.
Công bố quan sát đã hoàn tất. Nếu mọi trang đều thành công và không còn tín hiệu cục bộ mới, thay danh sách hiển thị và đánh dấu thế hệ đó đã xử lý. Sự kiện được commit sau đó sẽ tạo công việc làm mới tiếp theo.

Worker cần khôi phục các thế hệ chưa hoàn tất sau sự cố. Một cờ chỉ nằm trong bộ nhớ có thể làm mất yêu cầu làm mới. Dùng xử lý tuần tự hoặc cơ chế chặn ghi cũ để lượt đọc trước chậm hơn không ghi đè kết quả mới đã hoàn thành.

Cơ chế này phát hiện sự kiện mà ứng dụng nhận trong lúc đọc. Nó không chứng minh thành viên phía nguồn đã đứng yên: API không định nghĩa phiên bản snapshot dùng chung giữa các trang và webhook. Hãy hiển thị thời điểm quan sát gần nhất thay vì hứa danh sách luôn đúng tức thời. Sự kiện đến muộn có thể kích hoạt lượt đọc mới; không cần áp dụng phần thay đổi cũ để đưa danh sách về trạng thái trước đó.

Xử lý khi không có thông báo hoặc đọc thất bại

UnifyPort là giao diện không chính thức. Ma trận hỗ trợ sự kiện mô tả ánh xạ của parser, không bảo đảm mọi tài khoản phía nguồn đều phát mọi thông báo. Các sự kiện bị lỡ cũng không được bảo đảm phát lại. Nếu đội ngũ nhận cả Zalo và WhatsApp, không nên suy ra rằng Zalo có cùng sự kiện nhóm chỉ vì dùng chung cấu trúc bao ngoài.

Khởi tạo danh sách khi mở màn hình nhóm lần đầu, cung cấp nút làm mới rõ ràng và cân nhắc đối soát định kỳ có giới hạn cho các nhóm ứng dụng đang dùng. Chọn lịch theo nhu cầu vận hành; bài viết không khẳng định hạn mức polling hay bảo đảm độ mới của dữ liệu.

Lỗi truy vấn thành viên tự nó không chứng minh nhóm đã giải tán hoặc mọi người đã rời đi. Tách trạng thái không truy cập được và dữ liệu cũ khỏi danh sách rỗng. Người đang chờ duyệt cũng thuộc quy trình khác: group.join_request không phải xác nhận đã gia nhập.

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

Có thể dựng lại toàn bộ nhóm từ changes[].members[] không?

Không. Các mảng chỉ liệt kê người bị tác động bởi từng thay đổi, không phải tất cả thành viên hiện tại. Cần đọc danh sách với đầy đủ các trang.

data.actor có phải người gia nhập hoặc rời nhóm không?

Đó là người thực hiện thay đổi. Xem members[] tương ứng để biết người bị tác động và đọc danh sách để lấy thành viên hiện tại.

Có thể tự cấp quyền trong ứng dụng từ thay đổi vai trò không?

Không nên tự đồng nhất vai trò trên nền tảng nhắn tin với quyền của ứng dụng. Giữ chính sách phân quyền nhân viên riêng và kiểm tra lại trước thao tác nhạy cảm.

Bước tiếp theo và nguồn

Xây worker làm mới theo List conversation members. Nên kiểm thử người chỉ xuất hiện ở trang sau, lỗi trang giữa, sự kiện lặp, nhiều thay đổi trong một sự kiện, thay đổi mới khi đang phân trang và worker dừng trước lúc công bố. Đây là các bài kiểm thử đề xuất, không phải kết quả đã chạy.

Đối chiếu tài liệu ngày 2026-11-09:

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