Lấy liên kết mời nhóm WhatsApp qua API: đọc khác với đặt lại
Để lấy liên kết mời nhóm WhatsApp qua UnifyPort, gọi GET /v1/accounts/{account_id}/groups/invite-code với tham số truy vấn group_id. Phản hồi chứa data.invite_url và data.invite_code. Đọc liên kết không phải là đặt lại liên kết. WhatsApp có thao tác gốc để quản trị viên vô hiệu hóa liên kết và tạo liên kết mới; tài liệu công khai của UnifyPort mô tả việc lấy liên kết, không phải thao tác đặt lại.
Những điểm chính
- Chọn tài khoản nhắn tin cùng với nhóm đích; mã mời không phải ID nhóm.
- Gọi API từ máy chủ và chỉ hiển thị liên kết cho người vận hành có quyền.
- Tách việc lấy, chia sẻ, duyệt yêu cầu tham gia và đặt lại thành các thao tác riêng.
- Sau khi đặt lại trong WhatsApp, đọc lại liên kết hiện tại và thay những bản sao ứng dụng quản lý.
Endpoint lấy liên kết thực sự làm gì?
Hướng dẫn mời vào nhóm chính thức của WhatsApp mô tả lời mời qua liên kết và cảnh báo rằng người nhận có thể chuyển tiếp liên kết. Hướng dẫn cũng nêu việc quản trị viên vô hiệu hóa liên kết mời và tạo liên kết mới. Không nên coi thao tác trong ứng dụng đó là tác dụng của một lệnh đọc API.
Tài liệu lấy liên kết mời của UnifyPort quy định phạm vi hẹp hơn:
| Đầu vào hoặc đầu ra | Ý nghĩa |
|---|---|
account_id trong đường dẫn | Tài khoản nhắn tin đã kết nối dùng để thực hiện thao tác |
group_id trong truy vấn | Định danh nhóm phía nền tảng |
data.invite_url | URL lời mời được trả về |
data.invite_code | Mã mời được trả về, không phải ID cuộc trò chuyện |
Ma trận hỗ trợ thao tác hiện ánh xạ chức năng này cho whatsapp, không phải LINE, Telegram, Zalo hoặc nhà cung cấp riêng whatsapp-protocol. Nếu đội hỗ trợ quản lý cả Zalo lẫn WhatsApp, không nên tự động bật cùng nút lấy liên kết cho mọi kênh.
Tài liệu endpoint lưu ý rằng đa số nhà cung cấp yêu cầu quyền quản trị nhóm. Với quy trình này, hãy dùng tài khoản quản trị nhóm WhatsApp được phép sử dụng và xác minh quyền hiện tại. Quyền API của workspace không tự cấp quyền quản trị nhóm. Đây là giao diện không chính thức cho tài khoản đã kết nối, không phải endpoint WhatsApp Cloud API.
Lấy liên kết mà không lộ API Key
Trước hết, dùng Danh sách nhóm để chọn nhóm thuộc đúng tài khoản. Danh sách bao gồm các nhóm tài khoản đã tham gia ngay cả khi chưa dùng để nhắn tin. Đọc đủ các trang cần thiết và giữ lại id của mục được chọn; với nhóm, conversation_id bằng id. Đừng xác định nhóm chỉ bằng tên hiển thị vì tên có thể trùng nhau.
Đây là yêu cầu minh họa, không phải bản ghi kiểm thử đã thực hiện. Đặt các biến môi trường lần lượt thành API Key được giữ ở máy chủ, ID tài khoản đã chọn và ID nhóm lấy từ danh sách:
curl --get \
"https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/groups/invite-code" \
-H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
--data-urlencode "group_id=${WHATSAPP_GROUP_ID}"Định danh nền tảng có thể chứa ký tự như @, nên cần mã hóa tham số truy vấn đúng cách. Giữ khóa trên máy chủ; không đưa yêu cầu có khóa xác thực này vào JavaScript chạy trong trình duyệt.
Khi thành công, đọc data.invite_url và data.invite_code. Đừng tự ghép URL lời mời từ ID nhóm. Nếu phản hồi lỗi hoặc không có liên kết mong đợi, hiển thị lỗi hay trạng thái chưa khả dụng thay vì tự tạo một giá trị.
Để chẩn đoán, ghi lại HTTP status, mã lỗi và request_id của máy chủ. Hướng dẫn truy vết yêu cầu giải thích cách giữ bằng chứng mà không ghi toàn bộ nội dung phản hồi. Ở đây, phản hồi chứa liên kết mời nên không được đưa vào thuộc tính phân tích hay nhật ký thông thường của ứng dụng.
Thiết kế nút riêng cho từng mục đích
| Điều khiển | Hành vi mong muốn | Không có nghĩa là |
|---|---|---|
| Hiển thị liên kết hiện tại | Đọc và hiển thị kết quả API | Đã tạo liên kết mới |
| Sao chép liên kết | Sao chép URL để chia sẻ có thẩm quyền | Người nhận đã vào nhóm |
| Xem yêu cầu tham gia | Mở quy trình kiểm duyệt | Đã đặt lại liên kết |
| Đặt lại liên kết | Hướng quản trị viên đến thao tác trong WhatsApp | Có lệnh đặt lại UnifyPort đã được tài liệu hóa |
Kiểm tra quyền trong ứng dụng trước khi hiển thị hoặc sao chép. Tránh đưa liên kết vào bảng điều khiển công khai, ảnh chụp màn hình hỗ trợ hoặc thuộc tính sự kiện phân tích. Nếu lưu đệm, ghi rõ đó là giá trị đã lấy trước đây thay vì đảm bảo nó vẫn còn hiệu lực.
Duyệt yêu cầu tham gia là quy trình khác. Khi cần kiểm duyệt, tham khảo hàng đợi duyệt yêu cầu vào nhóm WhatsApp, trong đó danh sách chờ được đối chiếu trước khi quyết định. Lấy liên kết không bật chế độ duyệt và không phê duyệt bất kỳ người đăng ký nào.
Cập nhật bản sao sau khi đặt lại trong WhatsApp
Xét tình huống giả định: quản trị viên cho rằng lời mời đã bị chia sẻ quá rộng nên đặt lại trong WhatsApp, nhưng ứng dụng vẫn giữ URL cũ.
Quy trình vận hành được đề xuất:
- Tạm dừng phân phối liên kết trong bộ nhớ đệm khi quản trị viên thực hiện thao tác.
- Đọc lại endpoint cho cùng tài khoản và nhóm.
- Hiển thị kết quả vừa lấy để người có quyền kiểm tra.
- Thay liên kết do ứng dụng quản lý và các ảnh QR được tạo từ URL cũ.
- Thông báo cho người quản lý các kênh phân phối khác kiểm tra bản sao của họ.
Đây là khuyến nghị vận hành, không phải tính năng luân chuyển nguyên tử. Tài liệu công khai không định nghĩa tham số đặt lại, endpoint đặt lại, thời điểm hết hạn của liên kết hay webhook riêng xác nhận việc đặt lại. Đừng đoán trường dữ liệu hoặc coi việc không có sự kiện là bằng chứng liên kết chưa đổi. Nếu lần đọc mới thất bại, tiếp tục tạm dừng phân phối hoặc đánh dấu rõ là chưa xác minh, thay vì âm thầm khôi phục giá trị cũ.
Câu hỏi thường gặp
Mỗi lần gọi invite-code có tạo liên kết mới không?
Thao tác được tài liệu hóa là lấy liên kết và mã. Không có cam kết tạo mới hoặc luân chuyển liên kết sau mỗi lần đọc.
Có thể dùng invite_code làm group_id không?
Không. Dùng ID nhóm phía nền tảng đã chọn trong tài khoản kết nối. Mã mời là một giá trị trả về riêng.
Có thể đặt lại liên kết qua API này không?
Tài liệu công khai hiện tại không mô tả thao tác đó. Hãy dùng chức năng quản trị viên trong WhatsApp, rồi đọc lại liên kết hiện tại.
Đọc thất bại có nghĩa là nhóm đã bị xóa không?
Không. Hãy xem HTTP status và chi tiết lỗi. get_group_invite_code_failed chỉ lỗi lấy dữ liệu phía máy chủ hoặc hệ thống thượng nguồn, không phải bằng chứng nhóm bị xóa.
Bước tiếp theo và nguồn
Trước tiên, triển khai quy trình chỉ đọc theo Lấy liên kết mời nhóm. Trước khi đưa vào sử dụng, kiểm tra việc chọn nhóm, thiếu quyền, mã hóa truy vấn, che dữ liệu trong log và làm mới bản sao sau khi quản trị viên đặt lại có thẩm quyền. Đây là các bước kiểm thử đề xuất, không phải kết quả đã thực hiện.
Nguồn được đối chiếu ngày 2026-10-15:
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.