Chuyển chat WhatsApp giữa các nhãn: quy trình API an toàn

Để chuyển chat WhatsApp từ nhãn công việc này sang nhãn khác qua UnifyPort, cần hai thao tác thay đổi liên kết: thêm nhãn đích, kiểm tra kết quả rồi mới gỡ nhãn nguồn. Tài liệu công khai không cam kết thao tác chuyển nguyên tử. Hãy giữ các nhãn không liên quan và hiển thị rõ việc bàn giao chưa hoàn tất. Không xóa cả nhãn hoặc coi timeout là bằng chứng rằng chưa có thay đổi nào xảy ra.

Điểm chính

• action: "remove" gỡ nhãn khỏi các hội thoại đã chọn; xóa bản thân nhãn là thao tác khác.
• Nhiều nhãn có thể cùng tồn tại, nên chúng không buộc một chat chỉ có một người phụ trách hay một giai đoạn.
• Thêm trước khi gỡ giúp duy trì khả năng nhìn thấy chat, nhưng tạm thời sẽ có cả hai nhãn.
• Lưu bản ghi phân công chính và tiến độ bàn giao trong ứng dụng, không chỉ suy ra từ nhãn.

Xác định phần cần chuyển, không thay thế toàn bộ nhãn

Hướng dẫn về nhãn của WhatsApp mô tả cách sắp xếp chat và áp dụng nhiều nhãn cho cùng một chat. Trang này cũng cho biết nhãn đang dần được chuyển thành danh sách. Thay đổi thuật ngữ giao diện không có nghĩa trường label_id của UnifyPort đã đổi tên, hay mọi danh sách trong ứng dụng đều có API tương ứng.

Xét tình huống giả định: chat có nhãn “Chờ xử lý” và “VIP”; nhân viên muốn chuyển sang “Đang xử lý”. Thay đổi cần thực hiện là thêm “Đang xử lý”, gỡ “Chờ xử lý” và giữ “VIP”. Đây không phải thao tác thay toàn bộ nhãn bằng “Đang xử lý”.

Bản cập nhật API tháng Sáu đã giới thiệu các thao tác nhãn. Khi bàn giao, cần phân biệt đối tượng của từng thao tác:

Ý định	Thao tác	Đối tượng
Tạo hoặc đổi tên phân loại	Tạo hoặc cập nhật nhãn	Định nghĩa nhãn
Thêm nhãn đích	Liên kết action: "add"	Các hội thoại được chọn dưới nhãn đó
Gỡ nhãn nguồn	Liên kết action: "remove"	Các hội thoại được chọn dưới nhãn đó
Ngừng dùng một phân loại	Xóa nhãn	Bản thân nhãn, không phải liên kết của một chat

Không dùng lệnh xóa nhãn thay cho việc gỡ nhãn khỏi một hội thoại: các chat khác có thể vẫn dùng phân loại đó.

Chuẩn bị hai thao tác

Đọc danh mục nhãn của tài khoản nhắn tin đã chọn để lấy ID nguồn và đích. Theo hết phân trang; tên chỉ là nội dung hiển thị, không phải khóa định danh ổn định. Nếu cần tạo nhãn đích, dùng Tạo hoặc cập nhật nhãn và giữ lại data.id trong phản hồi.

Xác định conversation_id của chat trong cùng tài khoản. Không dùng tên nhãn, tên hiển thị liên hệ hoặc ID tin nhắn thay cho ID hội thoại. Kiểm tra ma trận hỗ trợ thao tác: hiện các thao tác nhãn này hỗ trợ whatsapp, không hỗ trợ LINE, Telegram, Zalo hay nhà cung cấp riêng whatsapp-protocol. Nếu đội hỗ trợ dùng cả Zalo và WhatsApp, hãy thiết kế phân loại Zalo ở tầng ứng dụng thay vì giả định cùng lệnh này dùng được cho cả hai.

Tài liệu liên kết nhãn quy định POST /v1/accounts/{account_id}/conversations/labels với label_id, action và mảng conversation_ids không rỗng.

Hàm JavaScript phía máy chủ dưới đây chỉ thực hiện một thao tác, cố ý không tự động chạy cả quy trình bàn giao. Truyền ID thật do backend chọn và API key được lưu an toàn. Đây là mã minh họa, không phải client production đã được kiểm thử.

async function changeLabelMembership({
  apiKey, accountId, labelId, conversationIds, action
}) {
  const validId = value => typeof value === 'string' && value.trim() !== '';
  if (!validId(accountId) || !validId(labelId) ||
      !Array.isArray(conversationIds) || conversationIds.length === 0 ||
      !conversationIds.every(validId) || !['add', 'remove'].includes(action)) {
    throw new Error('Select an account, label, conversations, and action');
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/conversations/labels`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        label_id: labelId,
        action,
        conversation_ids: [...new Set(conversationIds)]
      })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

Lần đầu dùng ID đích và add; lần sau dùng ID nguồn và remove cho cùng chat. Từ chối tại ứng dụng nếu ID nguồn trùng ID đích. Kiểm tra HTTP status và dữ liệu trả về: fetch hoàn tất bình thường không nhất thiết là thành công. Dữ liệu thành công được mô tả trong tài liệu xác định label_id, action và conversation_ids chịu tác động.

Đặt bước kiểm tra giữa thêm và gỡ

Đây là khuyến nghị thiết kế ứng dụng, không phải cam kết giao dịch của UnifyPort:

1. Lưu tài khoản, hội thoại, nhãn nguồn và đích trong hệ thống của bạn. Xác nhận nhân viên có quyền thay đổi phân công.
2. Thêm nhãn đích. Ghi phản hồi và request_id, không ghi API key.
3. Gọi Danh sách hội thoại với label_id đích được chỉ rõ. Xác nhận chat đã chọn xuất hiện trước khi gỡ nhãn nguồn.
4. Chỉ gỡ liên kết với nguồn, giữ nhãn độc lập như VIP.
5. Đối chiếu cả hai chế độ xem. Nếu kết quả chưa khớp trạng thái mong muốn, hiển thị công việc chưa hoàn tất.

Không dùng danh sách thiếu bộ lọc nhãn để xác minh đích. Theo hợp đồng API WhatsApp, bỏ qua label_id chỉ trả về hội thoại được đánh dấu quan tâm đặc biệt. Hướng dẫn chat bị thiếu và bộ lọc nhãn giải thích phạm vi này và phân trang. Không thấy chat ở trang đầu không chứng minh chat vắng mặt; đọc thất bại không phải kết quả rỗng. Đọc trực tiếp qua nhiều trang không được cam kết là ảnh chụp trạng thái bất biến.

Liên kết quan sát được	Ý nghĩa với lần bàn giao này	Hành động đề xuất
Chỉ có nguồn	Chưa quan sát được đích	Giữ nguồn và kiểm tra thao tác thêm
Có cả hai	Trạng thái trung gian hoặc người khác đã sửa	Xác nhận ý định hiện tại trước khi gỡ nguồn
Chỉ có đích	Quan sát được mẫu liên kết mong muốn	Ghi hoàn tất nếu phân công trong ứng dụng vẫn khớp
Không có cả hai hoặc đọc chưa đầy đủ	Chưa xác định được trạng thái	Giữ công việc cục bộ và kiểm tra, không đoán đã xong

Khôi phục mà không lặp lại ý định cũ

Tuần tự hóa các thay đổi của cùng hội thoại trong ứng dụng và loại bỏ công việc hàng đợi đã lỗi thời trước khi gửi. Nếu nhân viên khác đã đổi phân công, đừng tự động hoàn thành lần bàn giao cũ. Tuần tự hóa cục bộ không khóa được mọi client đã liên kết, nên vẫn cần đối chiếu thay đổi bên ngoài.

Nếu thao tác thêm timeout, giữ nhãn nguồn và kiểm tra đích trước khi quyết định tiếp. Nếu kết quả gỡ chưa rõ, đọc cả hai chế độ xem trước khi cân nhắc lặp lại. Không tự động gỡ đích để “hoàn tác”: người khác có thể đã dựa vào nhãn đó để làm việc.

Tài liệu công khai không cam kết tính nguyên tử giữa hai lần gọi, toàn bộ batch cùng thành công hoặc thất bại, điều kiện tiên quyết theo phiên bản, hay webhook riêng báo đổi nhãn. Với xử lý hàng loạt, lưu tiến độ theo từng hội thoại thay vì coi cả batch là một phân công đã hoàn tất. set_label_members_failed được tài liệu mô tả cho lỗi máy chủ hoặc hệ thống phía trên; unsupported_by_provider là giới hạn hỗ trợ, không phải lý do retry vô hạn.

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

Thêm nhãn mới có tự gỡ nhãn cũ không?

Không. API cung cấp thao tác thêm và gỡ riêng. Xử lý từng liên kết nhãn độc lập.

Nhãn có bảo đảm chỉ một người phụ trách không?

Hợp đồng này không bảo đảm điều đó. Lưu người phụ trách và quyền trong ứng dụng, rồi dùng nhãn làm hình chiếu quyết định ở phía nhà cung cấp.

conversation.updated có xác nhận bàn giao không?

Đừng giả định như vậy. Các thiết lập được mô tả gồm tắt thông báo, lưu trữ, ghim và trạng thái đọc, không phải biên nhận liên kết nhãn được bảo đảm.

Đây có phải thao tác chính thức của WhatsApp Cloud API không?

Không. Đây là endpoint của giao diện không chính thức UnifyPort cho tài khoản đã kết nối. Trợ giúp ứng dụng WhatsApp giải thích khái niệm phía người dùng, không định nghĩa hợp đồng API này.

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

Bắt đầu với Thêm hoặc gỡ nhãn trên hội thoại. Trong tài khoản có kiểm soát, kiểm thử bàn giao thành công, thêm đích thất bại, gỡ bị timeout, chỉnh sửa cạnh tranh, phân trang và giữ nhãn không liên quan trước khi bật chuyển hàng loạt. Đây là các bài 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-14:

• UnifyPort: Liên kết nhãn
• UnifyPort: Danh sách hội thoại
• UnifyPort: Sự kiện tiêu chuẩn
• WhatsApp Help Center: How to use labels