Hướng dẫn October 23, 2026

Đổi tên, mô tả và ảnh nhóm WhatsApp qua API

Để đổi tên, mô tả hoặc ảnh nhóm WhatsApp qua UnifyPort, gửi POST /v1/accounts/{account_id}/groups/update-info với group_id và ít nhất một trường trong name, description, avatar_url. Endpoint này yêu cầu quyền quản trị viên nhóm. Chỉ gửi các trường người vận hành muốn thay đổi, rồi đọc lại thông tin nhóm; đừng coi dữ liệu lúc mở trình chỉnh sửa là trạng thái hiện tại.

Điểm chính

Thông tin nhóm không phải nhãn riêng trong CRM. Cần làm rõ phạm vi trước khi lưu.
Giữ cố định tài khoản nhắn tin và ID nhóm đã chọn trong suốt phiên chỉnh sửa.
Gửi thay đổi nhỏ, rõ ràng thay vì gửi lại toàn bộ phản hồi đọc dữ liệu.
Đối chiếu từng trường; hết thời gian chờ hoặc không có webhook không chứng minh rằng chưa có thay đổi.

Chọn đúng trường, không gộp mọi thứ vào phần cài đặt

Hướng dẫn thay đổi thông tin nhóm của WhatsApp mô tả cách chỉnh sửa trong ứng dụng. Hướng dẫn cài đặt quản trị viên cũng giải thích quyền cho phép thành viên chỉnh sửa cài đặt nhóm. Tuy nhiên, tùy chọn trong ứng dụng không mở rộng hợp đồng API của UnifyPort: tài liệu Update group info yêu cầu rõ quyền quản trị viên.

Mục đích	Trường yêu cầu	Việc cần xử lý riêng
Đổi tên nhóm	`name`	Bí danh riêng trong hộp thư
Đổi mô tả nhóm	`description`	Phiếu hỗ trợ hoặc nội dung tin nhắn
Thay ảnh nhóm	`avatar_url`	Ảnh hồ sơ của thành viên

Nếu muốn đổi vai trò, dùng quy trình bổ nhiệm và gỡ quyền quản trị viên. Nếu muốn chia sẻ lời mời, dùng quy trình liên kết mời vào nhóm. Không đặt các thao tác đó trong biểu mẫu thông tin nhóm.

UnifyPort cung cấp giao diện không chính thức. Ma trận hỗ trợ thao tác theo kênh chỉ ánh xạ thao tác ghi này tới whatsapp, không phải LINE, Telegram hay kênh riêng whatsapp-protocol. Nếu đội ngũ dùng cả WhatsApp và Zalo, đừng suy ra mọi kênh có cùng khả năng quản lý nhóm. Đọc được nhóm hoặc nhận được sự kiện nhóm không đồng nghĩa với sửa được thông tin nhóm.

Dùng dữ liệu mới đọc để mở trình chỉnh sửa

Chọn nhóm bằng List groups dưới đúng tài khoản nhắn tin và xử lý phân trang. Giữ nguyên id được trả về; với nhóm, conversation_id bằng id. Tên chỉ là giá trị hiển thị, không phải định danh duy nhất.

Tiếp theo, gọi Get group để đọc thông tin hiện tại. Trong ứng dụng, lưu riêng:

Các giá trị quan sát được gần nhất.
Các trường người vận hành thực sự sửa.
Các giá trị đọc được sau khi gửi yêu cầu.

Nếu chỉ sửa mô tả, đừng gửi kèm tên và ảnh cũ. Nếu lần đọc mới cho thấy người khác đã sửa trường đang chỉnh, hãy yêu cầu người vận hành xem lại trước khi lưu. Đây là biện pháp bảo vệ ở ứng dụng, không phải cơ chế kiểm tra phiên bản phía máy chủ.

Màn hình xác nhận nên hiển thị tài khoản, nhóm và các trường thay đổi. Giữ API key ở backend và kiểm tra quyền người vận hành tại đó.

Chỉ gửi thay đổi thông tin nhóm có chủ đích

Đoạn JavaScript sau minh họa một yêu cầu từ backend. Truyền định danh thực tế của mục đã chọn và API key được lưu trên máy chủ. Ví dụ này chỉ cho phép thay bằng giá trị không rỗng; nó không định nghĩa thao tác xóa mô tả hay gỡ ảnh nhóm.

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

Chỉ đưa trường đã sửa vào edits. Ảnh nhóm cần URL hình ảnh truy cập công khai. Dùng ảnh bạn kiểm soát và có quyền công khai; không gửi đường dẫn tệp cục bộ hoặc trang yêu cầu đăng nhập bằng trình duyệt. Đây là yêu cầu dựa trên URL, không phải endpoint tải ảnh lên.

Phản hồi thành công được tài liệu quy định là 200 OK với data.ok: true. Kiểm tra cả hai trước khi báo thành công. Mã dùng trong môi trường thực còn phải xử lý lỗi mạng và phản hồi không phải JSON, giữ request_id khi có và không ghi thông tin xác thực vào log. Ví dụ chỉ để minh họa, chưa được chạy trong tác vụ này.

Đối chiếu từng trường thay vì gửi lại cả biểu mẫu

Sau yêu cầu, đọc lại đúng nhóm và so sánh tên, mô tả với giá trị đã gửi. Với ảnh, kiểm tra ảnh trả về hoặc ứng dụng WhatsApp thay vì yêu cầu URL trả về phải giống URL nguồn; hợp đồng không bảo đảm hai địa chỉ giống nhau.

Tài liệu sự kiện chuẩn mô tả group.updated với nhiều mục có thể xuất hiện trong data.changes[]:

renamed chứa name.
description_changed chứa description.
avatar_changed của WhatsApp chứa removed và có thể có picture_id, nhưng không có URL ảnh.

Dùng sự kiện làm tín hiệu để đối chiếu, không phải biên nhận được bảo đảm cho từng yêu cầu. Xác minh chữ ký theo hợp đồng gửi webhook, xử lý trùng lặp và sai thứ tự. Đừng xóa trường không liên quan chỉ vì sự kiện không chứa trường đó.

Khi hết thời gian chờ, đánh dấu kết quả chưa xác định và kiểm tra trạng thái hiện tại trước khi quyết định còn gì cần sửa. Không tự động gửi lại biểu mẫu nhiều trường cũ hay khôi phục ảnh chụp dữ liệu cũ. Tài liệu công khai không cung cấp hoàn tác nguyên tử nhiều trường hoặc điều kiện phiên bản. Việc phía nền tảng từ chối quyền được biểu diễn bằng update_group_info_failed; vẫn cần đọc chi tiết vì không thể coi mọi lỗi cùng mã là cùng nguyên nhân.

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

Có thể dùng giá trị rỗng để xóa mô tả hoặc gỡ ảnh không?

Quy trình này không giả định như vậy. Endpoint được trích dẫn không định nghĩa quy ước xóa giá trị. Không bật các nút đó trước khi xác nhận hợp đồng cho thao tác mong muốn.

Đọc thông tin nhóm thành công nghĩa là có thể sửa không?

Không. Quyền đọc, khả năng hỗ trợ thao tác của kênh và quyền quản trị viên nhóm cần được kiểm tra riêng.

Có phải gửi cả ba trường không?

Không. Chỉ cần group_id và ít nhất một trường chỉnh sửa được hỗ trợ. Biểu mẫu không thay đổi thì không nên gửi yêu cầu ghi.

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

Triển khai theo Update group info. Trước khi bật tính năng, kiểm tra sửa riêng tên, biểu mẫu chưa chỉnh, thay đổi đồng thời trong WhatsApp, ảnh không truy cập được, lỗi quyền và hết thời gian chờ. Đây là các kiểm thử đề xuất, không phải kết quả đã thực hiện.

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

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