Hướng dẫn October 16, 2026

Thêm và gỡ cảm xúc tin nhắn bằng UnifyPort

Để thêm cảm xúc qua UnifyPort, gọi POST /v1/messages/reaction với tài khoản, cuộc trò chuyện, tin nhắn, người gửi tin nhắn gốc và emoji đã chọn. Để gỡ cảm xúc hiện có của tài khoản đang kết nối, giữ nguyên đích và gửi emoji: "". Điểm quan trọng: sender_id chỉ tác giả của tin nhắn được thả cảm xúc, không phải nhân viên thao tác hay một người bất kỳ mà bạn muốn sửa cảm xúc của họ.

Những điểm chính

Thao tác gửi hiện hỗ trợ whatsapp và telegram; nhận sự kiện cảm xúc là khả năng riêng.
Lấy đích từ tin nhắn gốc đã chọn, không dùng ID của bản thân cảm xúc trong sự kiện.
Khi thả cảm xúc vào tin nhắn của người khác, truyền rõ sender_id; nếu bỏ qua, giá trị mặc định là tài khoản đang kết nối.
Thêm và gỡ phải là hai ý định rõ ràng, không phải nút đảo trạng thái được thử lại sau mọi lỗi.

Ánh xạ các trường về tin nhắn gốc

Tài liệu React to message mô tả thao tác trên tin nhắn đã tồn tại. Đây không phải gửi một tin nhắn văn bản chứa emoji, cũng không dùng token trả lời trích dẫn.

Trường yêu cầu	Nguồn trong sự kiện `message.received` đã lưu
`account_id`	`account_id` ở cấp cao nhất
`conversation_id`	`data.conversation.id`
`message_id`	`data.message.id`
`sender_id`	`data.sender.id`, tác giả tin nhắn gốc
`emoji`	Emoji được chọn, hoặc chuỗi rỗng để gỡ

Trong nhóm, mã cuộc trò chuyện xác định nhóm còn mã người gửi xác định thành viên. Đừng thay mã cuộc trò chuyện bằng mã người gửi chỉ vì chúng trông giống nhau trong chat riêng. Giữ nguyên định danh do nền tảng trả về, không tự ghép từ tên liên hệ hoặc số điện thoại.

Nếu bắt đầu từ sự kiện message.reaction, cần phân biệt thêm: data.message.id xác định bản thân cảm xúc, còn data.message.target_message_id trỏ đến tin nhắn gốc. Người gửi của sự kiện này là người thả cảm xúc, không nhất thiết là tác giả tin nhắn gốc. Hãy tìm lại bản gốc đã lưu trước khi tạo thao tác mới. Hướng dẫn xử lý webhook cảm xúc giải thích luồng nhận và cập nhật trạng thái; bài này tập trung vào yêu cầu gửi riêng biệt.

Tạo yêu cầu thêm hoặc gỡ rõ ràng

Đoạn JavaScript sau chỉ minh họa cách tạo yêu cầu, không phải kiểm thử tích hợp đã chạy hay bộ nhận webhook hoàn chỉnh. Đầu vào là sự kiện gốc đã được xác thực chữ ký, lưu bền vững và được nhân viên có quyền lựa chọn. Tên hàm và thông báo lỗi thuộc mã ứng dụng.

function buildReactionRequest(original, emoji) {
  if (original.type !== 'message.received' ||
      !['whatsapp', 'telegram'].includes(original.provider)) {
    throw new Error('Select a supported original message');
  }

  const conversation = original.data?.conversation;
  const message = original.data?.message;
  const sender = original.data?.sender;
  if (!original.account_id || !conversation?.id ||
      !message?.id || !sender?.id) {
    throw new Error('Original message context is incomplete');
  }
  if (typeof emoji !== 'string') {
    throw new Error('Choose an emoji or an empty string');
  }

  return {
    account_id: original.account_id,
    conversation_id: conversation.id,
    message_id: message.id,
    sender_id: sender.id,
    emoji
  };
}

Truyền "👍" để yêu cầu thêm cảm xúc và "" để gỡ. Hàm chỉ kiểm tra ngữ cảnh và kiểu dữ liệu, không bảo đảm nền tảng chấp nhận mọi emoji. Không dùng null, bỏ trường hoặc thêm cờ remove không có trong tài liệu để thay chuỗi rỗng.

Gửi JSON đã tạo từ backend đến POST /v1/messages/reaction bằng X-Api-Key. Không đưa khóa vào mã trình duyệt. Trước khi gửi, kiểm tra quyền của nhân viên đối với tài khoản nhắn tin và tin nhắn đích, đồng thời cố định lựa chọn để tin nhắn mới không làm đổi đối tượng thao tác.

Nếu muốn trả lời bằng một câu có trích dẫn thay vì cảm xúc, hãy dùng quy trình trả lời trích dẫn WhatsApp. reply_token dạng opaque của quy trình đó không phải mã cảm xúc.

Bật nút theo khả năng thao tác, không suy từ sự kiện

Ma trận thao tác theo nhà cung cấp và ma trận sự kiện webhook hiện mô tả hai khả năng khác nhau:

Nhà cung cấp	Gửi cảm xúc qua API này	Ánh xạ sự kiện cảm xúc
`whatsapp`	Có hỗ trợ	Có hỗ trợ
`telegram`	Có hỗ trợ	Có hỗ trợ
`line`	Không hỗ trợ	Có hỗ trợ
`twitter`, `zalo`, `tiktok`, `whatsapp-protocol`	Không hỗ trợ	Không hỗ trợ

Đây là ánh xạ adapter trong tài liệu, không bảo đảm khả dụng cho mọi tài khoản hoặc điều kiện phía nền tảng. Hộp thư LINE có thể hiển thị cảm xúc nhận được nhưng không có nút gửi hoạt động. Với hộp thư kết hợp WhatsApp và Zalo, cũng không nên mở cùng một thao tác cho cả hai chỉ vì dùng chung giao diện. Tổ hợp không hỗ trợ trả về 501 unsupported_by_provider; gọi lặp lại không tạo thêm khả năng.

UnifyPort cung cấp giao diện không chính thức cho tài khoản được kết nối. Bot API chính thức của Telegram định nghĩa riêng setMessageReaction cho bot. Khi cần danh tính bot, hãy dùng hợp đồng API gốc tương ứng; không sao chép cấu trúc yêu cầu sang endpoint này hoặc mặc nhiên áp dụng các giới hạn của Bot API cho UnifyPort.

Tách ý định, kết quả yêu cầu và trạng thái quan sát

Tài liệu endpoint minh họa phản hồi thành công 200 OK với data.ok: true. Lưu kết quả HTTP thực tế và request_id được trả về, nhưng đừng coi đó là bằng chứng người khác đã nhìn thấy cảm xúc.

Khuyến nghị cho ứng dụng:

Thực hiện tuần tự các thao tác trên cùng tài khoản và tin nhắn đích. Không để tác vụ thêm cũ chạy tùy tiện sau thao tác gỡ mới hơn.
Lưu emoji mong muốn trước khi gửi và lưu kết quả HTTP riêng.
Với react_message_failed, kiểm tra lỗi cùng đích ban đầu. Khi hết thời gian chờ, giữ kết quả ở trạng thái chưa rõ; không tự gửi thao tác ngược lại để bù.
Khi nhận sự kiện phù hợp, cập nhật trạng thái quan sát theo cách idempotent. Không giả định mọi yêu cầu đều có callback hay callback luôn đến đúng thứ tự.

Phía nhận cần cấu hình signing_secret và tuân theo tài liệu giao webhook: xác minh HMAC-SHA256 trên timestamp, dấu chấm và phần thân nguyên bản, kiểm tra độ mới của thời gian, rồi lưu bền vững trước khi xác nhận. Việc nhận webhook không tự cấp quyền khởi chạy một thao tác gửi mới.

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

Trước khi bật nút, hãy thử tin nhắn riêng nhận được, tin nhắn của thành viên nhóm khác, tin nhắn do tài khoản tự gửi, gỡ bằng chuỗi rỗng, nhà cung cấp không hỗ trợ và kết quả mạng chưa rõ. Xác nhận rằng tin nhắn mới không đổi đích đã chọn. Đây là danh sách kiểm thử đề xuất, không phải kết quả đã thực hiện.

sender_id có chọn người thả cảm xúc không?

Không. Trường này chỉ tác giả tin nhắn được thả cảm xúc. Tài khoản đang kết nối thực hiện thao tác; trường này không cho phép giả danh người khác.

Gửi lại cùng emoji có gỡ cảm xúc không?

Cách gỡ được tài liệu quy định là emoji: "". Không giả định hành vi đảo trạng thái.

Vì sao nhận được cảm xúc LINE nhưng không gửi được?

Phân tích sự kiện đầu vào và thao tác đầu ra có ma trận hỗ trợ riêng. Thao tác gửi cảm xúc hiện hỗ trợ Telegram và WhatsApp.

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

Triển khai kiểm tra đích theo React to message trước khi thêm nút vào hộp thư. Khi chưa đủ bằng chứng, giữ trạng thái chưa xác định; không tự suy ra API đọc cảm xúc hoặc cơ chế phát lại được bảo đảm.

Đối chiếu ngày 2026-10-16:

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