Hướng dẫn October 10, 2026

Nhắc tên trong nhóm qua UnifyPort: sửa thẻ dạng văn bản trên WhatsApp và LINE

Nếu tin nhắn nhóm qua UnifyPort hiển thị nguyên dấu đánh dấu nhắc tên, hãy kiểm tra cả hai phần của yêu cầu: mảng mentions ở cấp cao nhất khai báo thành viên, còn {{@<id>}} trong message.text hoặc message.caption xác định vị trí hiển thị. Dấu đánh dấu phải khớp ID đầy đủ trong mảng, hoặc phần ID đứng trước @. Nếu không khớp, nó được gửi như văn bản thông thường — không có nghĩa toàn bộ tin nhắn đã gửi thất bại.

Điểm cần nhớ

Chỉ viết tên hiển thị như @Alex không thay thế được cấu trúc nhắc tên trong tài liệu.
Đặt mentions ngang cấp với message, không đặt trong provider_data.
Hợp đồng này hỗ trợ nhắc tên trong văn bản và chú thích phương tiện của WhatsApp; LINE chỉ hỗ trợ văn bản.
Các nhà cung cấp khác bỏ qua mentions. Gửi thành công không chứng minh việc nhắc tên đã hoạt động.

Ghép đúng nhóm, thành viên và dấu đánh dấu

Tài liệu gửi nhắc tên phân biệt ba đầu vào:

Đầu vào	Mục đích	Lỗi thường gặp
`to.id` cùng `to.type: group`	Chọn nhóm nhận	Dùng thành viên được nhắc làm đích gửi
`mentions[].id` ở cấp cao nhất	Xác định người được nhắc	Chỉ cung cấp tên hiển thị
Dấu đánh dấu trong nội dung hoặc chú thích	Chọn vị trí thẻ	Dùng ID không có trong mảng

Ví dụ về cú pháp: với ID 100000000000002@lid, quy tắc cho phép {{@100000000000002@lid}} hoặc {{@100000000000002}}. Đây không phải người nhận thật. Khi sinh nội dung, nên dùng ID đầy đủ để quan hệ đối chiếu rõ ràng. Không tự đổi hậu tố ID hay đoán ID từ tên.

Ở kênh có hỗ trợ, dùng danh sách thành viên cuộc trò chuyện để kiểm tra thành viên của nhóm đã chọn. Mỗi mục có peer_id và display_name; danh sách hỗ trợ phân trang. Luôn giữ phạm vi tài khoản nhắn tin và nhóm khi chọn danh tính. Tên hiển thị là nhãn, không phải khóa định danh.

Nhắc tên cũng khác với trích dẫn một tin nhắn. Hướng dẫn trả lời có trích dẫn trên WhatsApp dùng token trả lời dạng opaque để chọn nội dung. Nhắc tên chọn người; trích dẫn chọn tin nhắn. Không hoán đổi các trường của hai thao tác.

Tạo cả hai phần từ cùng một lựa chọn

Đoạn JavaScript dưới đây thuộc ứng dụng và chỉ tạo yêu cầu văn bản, không phải chương trình gửi hoàn chỉnh. Tham số phải đến từ tài khoản, nhóm và ID thành viên đã xác minh do nhân viên có quyền chọn; nội dung phải được duyệt. Kiểm tra cục bộ này cố ý chặt hơn API: bản nháp không được tự thêm dấu đánh dấu nhắc tên.

function buildGroupMention({ provider, accountId, groupId, memberId, text }) {
  if (!['whatsapp', 'line'].includes(provider)) {
    throw new Error('Mention sending is not enabled for this provider');
  }
  if (![accountId, groupId, memberId, text].every(
    value => typeof value === 'string' && value.trim().length > 0
  )) {
    throw new Error('Account, group, member, and text are required');
  }
  if (/[{}\s]/u.test(memberId) || text.includes('{{@')) {
    throw new Error('Use the selected member to create the mention marker');
  }
  return {
    account_id: accountId,
    to: { id: groupId, type: 'group' },
    message: { type: 'text', text: `{{@${memberId}}} ${text}` },
    mentions: [{ id: memberId }]
  };
}

Gửi JSON thu được đến POST /v1/messages với xác thực X-Api-Key ở máy chủ. Hàm này không kiểm tra tư cách thành viên, quyền nhân viên hay trạng thái sẵn sàng của tài khoản; cần kiểm tra riêng trước khi gửi. Xác thực thành công cũng khác với kết nối đang hoạt động.

Nếu nhắc nhiều người, hãy tạo danh sách ID đã chọn và mọi dấu đánh dấu cùng lúc. Sau khi áp dụng mẫu hoặc để AI soạn nháp, kiểm tra yêu cầu JSON cuối cùng. Không để bước biến đổi sau đó xóa một phần tử mảng nhưng giữ lại dấu đánh dấu tương ứng.

Chẩn đoán trước khi gửi lại

Hiện tượng	Điểm kiểm tra	Cách xử lý
Hiện nguyên `{{@...}}`	Đối chiếu dấu đánh dấu với ID	Sinh cả hai từ cùng thành viên đã chọn
Dùng `provider_data.mentions`	Vị trí trường cũ	Chuyển sang `mentions` cấp cao nhất; trường cũ không còn được áp dụng
Bản nháp chỉ có `@Alex`	Thiếu ID có cấu trúc và dấu đánh dấu	Chọn thành viên rồi tạo cả hai đầu vào
Chú thích phương tiện LINE có nhắc tên	Khả năng hỗ trợ nội dung	Nếu chuyển sang tin nhắn văn bản riêng, cần duyệt rõ ràng, không tự gửi thêm
Telegram, X, Zalo hoặc TikTok có `mentions`	Ranh giới nhà cung cấp	Tắt chức năng nhắc tên này, không coi việc chấp nhận yêu cầu là gắn thẻ thành công

Các quy tắc dựa trên bảng hỗ trợ tin nhắn hiện tại, không đảm bảo mọi tài khoản hay hệ thống nguồn đều giống nhau. whatsapp-protocol là nhà cung cấp riêng, không kế thừa hỗ trợ nhắc tên của WhatsApp.

Đội ngũ dùng cả WhatsApp và Zalo không nên bật cùng một nút nhắc tên chỉ vì cả hai gửi qua một endpoint. Với chú thích WhatsApp, yêu cầu phương tiện vẫn phải hợp lệ. Xem hướng dẫn xử lý lỗi gửi phương tiện để kiểm tra nguồn tệp và giao nhận; sửa cú pháp nhắc tên không khắc phục URL hỏng.

Tách biệt cú pháp LINE gốc

Tài liệu loại tin nhắn chính thức của LINE mô tả tin nhắn văn bản v2, cho phép thay chuỗi trong dấu ngoặc nhọn bằng nhắc tên và emoji. Đây là hợp đồng Messaging API gốc, không có nghĩa đối tượng LINE thay thế trực tiếp được message và mentions cấp cao nhất của UnifyPort.

Khi tích hợp trực tiếp API chính thức, hãy dùng tài liệu gốc. UnifyPort cung cấp giao diện không chính thức. Endpoint chung không tái tạo mọi tính năng gốc và không đảm bảo người nhận nhìn thấy thông báo.

Kiểm tra nghiệm thu và câu hỏi thường gặp

Trước khi bật chức năng, hãy kiểm tra trong môi trường được cho phép: ID đầy đủ khớp, dấu đánh dấu cố ý không khớp, trường cũ, nhắc tên văn bản LINE và nhà cung cấp không hỗ trợ. Xem cả kết quả HTTP lẫn cách hiển thị ở phía nhận. Đây là đề xuất kiểm tra, không phải kết quả đã chạy.

accepted có chứng minh người dùng đã được nhắc hoặc nhận thông báo không?

Không. Tách riêng việc chấp nhận yêu cầu, giao tin, hiển thị nhắc tên và thông báo. Hết thời gian chờ cũng không chứng minh chưa gửi; cần điều tra trước khi lặp lại yêu cầu.

Có thể dùng nguyên data.message.mentions đầu vào làm yêu cầu gửi không?

Không thể sao chép nguyên trạng. Tài liệu sự kiện mô tả trường đầu vào tùy chọn data.message.mentions. Đầu ra dùng mentions ở cấp cao nhất và ID phải khớp dấu đánh dấu đã sinh. Kiểm tra đích gửi và những người thực sự cần nhắc, thay vì tự động nhắc tất cả người xuất hiện trong tin nhắn đến.

Có hoạt động với mọi kênh đã kết nối không?

Không. Hợp đồng này hỗ trợ văn bản và chú thích WhatsApp, cùng văn bản LINE. Các nhà cung cấp khác bỏ qua trường này.

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

Bắt đầu với đặc tả yêu cầu nhắc tên trong nhóm và một thành viên được chọn rõ ràng trước khi bật trả lời nhóm tự động tạo nội dung.

Tài liệu được kiểm tra ngày 2026-10-10:

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