Hướng dẫn October 24, 2026

Tạo nhóm WhatsApp qua API: xác nhận ID và thành viên ban đầu

Để tạo nhóm WhatsApp qua UnifyPort, gửi POST /v1/accounts/{account_id}/groups/create với name bắt buộc và mảng members tùy chọn. Trong yêu cầu tạo này, thành viên ban đầu của WhatsApp được xác định bằng số điện thoại. Phản hồi thành công trả về data.id, không phải báo cáo tham gia của từng người. Hãy lưu ID ngay, sau đó đọc thông tin nhóm và thành viên trước khi chạy các tác vụ tự động phụ thuộc vào kết quả đó.

Những điểm chính

Tạo nhóm, mời người tham gia và quản lý thành viên hiện có là các thao tác khác nhau.
members lúc tạo dùng số điện thoại; quản lý thành viên về sau dùng quy định định danh khác.
Danh mục sự kiện công khai không có group.created. Đừng chờ sự kiện này để hoàn tất quy trình.
Không nhận được phản hồi nghĩa là kết quả chưa rõ. Tự động gửi lại có thể tạo thêm một nhóm khác.

Đọc hợp đồng API trước khi thiết kế biểu mẫu

Tài liệu Create group quy định hợp đồng dưới đây. UnifyPort cung cấp giao diện không chính thức cho tài khoản nhắn tin đã kết nối, không phải endpoint của WhatsApp Cloud API. Ma trận hỗ trợ thao tác hiện chỉ ánh xạ việc tạo nhóm tới whatsapp, không bao gồm LINE, Telegram hay nhà cung cấp riêng whatsapp-protocol. Không nên suy rộng thao tác này sang các kênh khác, kể cả khi hộp thư của đội ngũ có cả WhatsApp và Zalo.

Giá trị	Ý nghĩa	Không được dùng thay thế
`account_id` trong đường dẫn	Tài khoản thực hiện tạo nhóm	ID workspace
`name` trong body	Tên nhóm bắt buộc, tối đa 100 ký tự	Định danh tài nguyên duy nhất
`members` trong body	Thành viên ban đầu tùy chọn; WhatsApp dùng số điện thoại	Mảng LID sao chép từ danh sách thành viên
`data.id` trong phản hồi	ID nhóm vừa tạo	Mã mời hoặc ID thao tác

Đối tượng data của phản hồi tạo chỉ chứa ID nhóm mới, không có kết quả thêm từng người. Hãy lưu riêng “thành viên ban đầu mong muốn” và “thành viên thực tế quan sát được sau đó”.

Hướng dẫn quản lý thành viên chính thức của WhatsApp mô tả việc thêm người, gửi lời mời và xem yêu cầu đang chờ khi bật phê duyệt. Đây là những hành trình khác nhau, không phải bằng chứng có thể dùng thay nhau rằng một người đã tham gia. Nếu muốn người dùng tự quyết định vào nhóm hiện có, hãy dùng quy trình liên kết mời thay vì tạo thêm nhóm.

Chuẩn bị một lần tạo có xác nhận

Theo tài liệu vòng đời tài khoản, xác nhận tài khoản đã được cấp quyền và runtime đang ở trạng thái running. Giữ API key ở backend và kiểm tra quyền của người thao tác tại đó.

Các biện pháp được khuyến nghị ở phía ứng dụng:

Hiển thị tài khoản, tên nhóm dự kiến và người tham gia trước khi xác nhận. Chỉ thêm những người đã biết và dự kiến tham gia.
Lưu ý định tạo nhóm trong hệ thống trước khi gửi. Người thao tác và dữ liệu dự kiến thuộc bản ghi của ứng dụng, không phải các trường API tự thêm.
Ngăn gửi đồng thời cho cùng một ý định tại backend. Chỉ vô hiệu hóa nút trên trình duyệt là chưa đủ.
Gửi một yêu cầu và lưu kết quả trước khi cho phép các bước tiếp theo.

Ví dụ JavaScript phía máy chủ dưới đây dựng yêu cầu theo tài liệu từ dữ liệu đã xác nhận. Mã chưa được chạy trong nhiệm vụ này và chủ động không có cơ chế tự gửi lại:

async function createGroupOnce({ apiKey, accountId, name, phones }) {
  if (!apiKey || !accountId || typeof name !== 'string' || !name.trim()) {
    throw new Error('Missing credential, account, or group name');
  }
  const body = { name };
  if (phones !== undefined) {
    if (!Array.isArray(phones) ||
        phones.some(p => typeof p !== 'string' || !/^[0-9]+$/.test(p))) {
      throw new Error('Use confirmed phone-number strings');
    }
    body.members = phones;
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/create`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

Dùng số điện thoại thực đã xác nhận theo định dạng trong tài liệu. Kiểm tra chữ số chỉ là lớp kiểm tra đầu vào cục bộ, không chứng minh chủ số đó có thể được thêm vào nhóm. Cần kiểm tra cả giới hạn độ dài tên. Mã dùng trong môi trường thật phải xử lý lỗi mạng và phản hồi không phải JSON, lưu request_id an toàn khi có, đồng thời tránh ghi thông tin xác thực hoặc danh sách số điện thoại vào log.

Tách lưu ID nhóm khỏi xác minh thành viên

Khi nhận 200 OK với data.id, lưu bền vững ID cùng tài khoản đã chọn và ý định tạo trong hệ thống. Sau đó gọi Get group, truyền ID đó dưới tên group_id.

Để kiểm tra người tham gia, dùng List conversation members với ID nhóm trong conversation_id và type=group. Đọc đủ các trang theo has_more và next_cursor; không thấy một người ở trang đầu chưa có nghĩa là đã kiểm tra xong. Giữ nguyên peer_id và role trả về, không suy ra LID từ số điện thoại.

Quản lý thành viên nhóm về sau có hợp đồng riêng: mỗi yêu cầu chỉ nhận một member_id và một action. Với WhatsApp, dùng LID mà danh sách thành viên trả về trong peer_id. Không tái sử dụng nguyên payload tạo nhóm. Nếu bước tiếp theo là bổ nhiệm quản trị viên, xem hướng dẫn thay đổi vai trò quản trị.

Điều quan sát được	Trạng thái ứng dụng nên dùng	Bước tiếp theo
Phản hồi thành công và đã lưu ID	Đã tạo; chưa xác minh thành viên	Đọc nhóm và toàn bộ trang thành viên
Đọc được nhóm nhưng chưa xác nhận đủ thành viên dự kiến	Nhóm tồn tại; thành viên cần kiểm tra	Kiểm tra ánh xạ định danh hoặc ứng dụng WhatsApp
Hết thời gian chờ, không đọc được phản hồi hoặc thiếu ID	Kết quả tạo chưa xác định	Đối chiếu trước khi cân nhắc tạo lại

Đây là trạng thái do ứng dụng quản lý, không phải giá trị phản hồi API bổ sung.

Khôi phục kết quả mà không tạo nhóm trùng

Danh mục sự kiện chuẩn không có group.created; tạo thành công không hứa hẹn callback đó. group.updated cũng không phải biên nhận được đảm bảo cho từng yêu cầu tạo.

Nếu mất phản hồi, kiểm tra List groups bằng cùng tài khoản và đọc đủ các trang. Danh sách bao gồm nhóm tài khoản đã tham gia dù chưa có hoạt động nhắn tin. Dùng thông tin hiện có và ứng dụng WhatsApp để điều tra. Chỉ trùng tên không chứng minh đó là cùng nhóm; đọc lỗi hoặc thiếu trang cũng không chứng minh việc tạo đã thất bại.

Hợp đồng tạo công khai không mô tả khóa idempotency. Bản ghi ý định cục bộ giúp ngăn ứng dụng của bạn gửi trùng, nhưng không bảo đảm thao tác phía nền tảng chỉ chạy đúng một lần. Trong khi kết quả chưa rõ, hãy tạm dừng lời mời và tin nhắn tự động liên quan, đồng thời yêu cầu người vận hành xem xét trước lần tạo tiếp theo.

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

Có thể bỏ members không?

Có, API quy định members là tùy chọn. Tuy nhiên, đây là thuộc tính của cấu trúc yêu cầu, không bảo đảm hành vi của mọi tài khoản phía nền tảng. Vẫn cần kiểm tra kết quả thực tế.

HTTP thành công có chứng minh tất cả đã tham gia không?

Không. Kết quả được tài liệu mô tả là ID nhóm, không phải kết quả từng người. Hãy đọc danh sách thành viên riêng.

Có thể truyền mô tả và ảnh nhóm ngay khi tạo không?

Chúng không được tài liệu liệt kê là trường tạo. Sau khi tạo, dùng quy trình chỉnh sửa thông tin nhóm riêng.

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

Triển khai theo tài liệu Create group. Trước khi bật chức năng, hãy kiểm thử nhấp đúp, mất phản hồi, nhóm trùng tên, phân trang thành viên và người không thể được thêm bằng các tài khoản bạn kiểm soát. Đây là đề xuất kiểm thử, không phải kết quả đã thực hiện.

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

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