Ghim cuộc trò chuyện hay tin nhắn WhatsApp: Chọn đúng API

Ghim cuộc trò chuyện trên WhatsApp giúp bạn tìm cuộc trò chuyện dễ hơn trong danh sách. Ghim tin nhắn làm nổi bật một nội dung cụ thể bên trong cuộc trò chuyện đó. Đây không phải cùng một cài đặt. Với hộp thư dùng API, hãy chọn đối tượng trước: cuộc trò chuyện cần ID hội thoại; tin nhắn cần thêm ID riêng và nên có ID người gửi rõ ràng nếu đó là tin của người khác.

Điểm chính

• Ghim cuộc trò chuyện quản lý danh sách chat của tài khoản đã kết nối; ghim tin nhắn chọn nội dung bên trong chat.
• UnifyPort dùng các endpoint khác nhau, với cách bỏ ghim khác nhau.
• Ghim cuộc trò chuyện không có tham số thời hạn. Ghim tin nhắn có duration_seconds tùy chọn.
• pinned trong conversation.updated mô tả trạng thái danh sách chat, không phải một tin nhắn được ghim.

Ghim cuộc trò chuyện khác ghim tin nhắn ở đâu?

Hướng dẫn nhắn tin cho chính mình của WhatsApp nói đến việc ghim chat lên đầu danh sách. Hướng dẫn ghim tin nhắn yêu cầu chọn một tin cụ thể và thời hạn ghim. Cùng dùng từ “ghim” nhưng đối tượng khác nhau.

Mục đích	Đối tượng	Không có nghĩa là
Dễ tìm cuộc trò chuyện với khách hàng	Một mục trong danh sách chat	Một tin cụ thể của khách cũng được làm nổi bật
Làm nổi bật hướng dẫn trong nhóm	Một tin nhắn	Nhóm sẽ chuyển lên đầu hộp thư
Giao việc khẩn cấp cho nhân viên	Phiếu hỗ trợ hoặc hàng đợi của ứng dụng	Ghim trên nền tảng sẽ tạo người phụ trách hay hạn xử lý

Theo trợ giúp chính thức, ghim tin nhắn trong nhóm tạo thông báo hệ thống cho biết ai đã ghim. Quản trị viên có thể quyết định thành viên có được ghim hay không. Vì vậy, đừng mô tả thao tác này như dấu trang riêng của nhân viên. Thiếu lịch sử trò chuyện cũng có thể khiến người dùng không nhìn thấy tin đã ghim; ghim không khôi phục nội dung bị thiếu.

Nếu chỉ cần nhắc việc riêng trong hệ thống hỗ trợ của bạn, nên dùng dấu trang do ứng dụng quản lý thay vì âm thầm thay đổi trạng thái nền tảng. Đây là khuyến nghị thiết kế, không phải tính năng API bổ sung.

Chọn hợp đồng UnifyPort theo đúng đối tượng

Các thao tác dưới đây thuộc giao diện không chính thức của UnifyPort, không phải Meta Cloud API.

Chi tiết	Ghim cuộc trò chuyện	Ghim tin nhắn
Method và đường dẫn	POST /v1/accounts/{account_id}/conversations/pin	POST /v1/messages/pin
Chọn tài khoản	account_id trong URL	account_id trong JSON
Mục tiêu trong JSON	conversation_id	conversation_id, message_id; đặt sender_id cho tin của người khác
Chọn trạng thái	Đường dẫn yêu cầu ghim	pinned: true để ghim, pinned: false để bỏ ghim
Thời hạn	Không có tham số thời hạn	Có thể truyền duration_seconds khi ghim
Bỏ ghim	Endpoint riêng cho cuộc trò chuyện	Cùng endpoint tin nhắn với pinned: false

Trước khi tạo request, kiểm tra tài liệu ghim cuộc trò chuyện, bỏ ghim cuộc trò chuyện và ghim hoặc bỏ ghim tin nhắn.

Đừng sao chép tùy chọn thời hạn trên giao diện ứng dụng thành tham số API cuộc trò chuyện. Cũng đừng gửi pinned: false đến endpoint ghim cuộc trò chuyện rồi mong nó bỏ ghim. Hãy theo đúng hợp đồng của thao tác đang gọi.

Ma trận hỗ trợ thao tác hiện ánh xạ ghim và bỏ ghim cuộc trò chuyện cho WhatsApp và LINE, nhưng ghim tin nhắn chỉ cho WhatsApp. Tổ hợp không được hỗ trợ trả về 501 unsupported_by_provider. Một giao diện chung không có nghĩa mọi kênh có cùng khả năng. Nếu hộp thư tại Việt Nam dùng cả WhatsApp và Zalo, đừng tự bật các nút ghim cho Zalo; tương tự, hỗ trợ ghim chat LINE không đồng nghĩa hỗ trợ ghim tin nhắn LINE.

Giữ đúng tin đã chọn, không thay bằng tin mới nhất

Với tin nhắn được chọn từ sự kiện message.received đã lưu, ánh xạ được tài liệu quy định là:

• account_id ở cấp cao nhất của sự kiện → account_id;
• data.conversation.id → conversation_id;
• data.message.id → message_id;
• data.sender.id → sender_id.

Tài liệu ghim tin nhắn quy định rằng nếu bỏ sender_id, hệ thống mặc định dùng chính tài khoản đã kết nối. Hãy đặt rõ người gửi khi ghim tin của thành viên khác. Trong nhóm, ID cuộc trò chuyện là nhóm, còn ID người gửi là tác giả; không hoán đổi chúng.

Giữ nguyên lựa chọn trong lúc nhân viên cân nhắc và xác nhận. Tin mới đến không được thay thế ID mục tiêu. Trước khi gửi request, hãy kiểm tra nhân viên có quyền thao tác trên tài khoản nhắn tin và cuộc trò chuyện đó hay không.

Tin nhắn có trích dẫn còn có một điểm dễ nhầm: ID tin gốc được trích dẫn không phải ID của chính tin đang chọn. Hướng dẫn trả lời trích dẫn WhatsApp giải thích mối quan hệ này. Ghim dùng ID của tin đã chọn, không dùng reply_token và không tự chuyển sang ID tin cha.

Xác nhận kết quả ở đúng cấp

Ví dụ thành công của cả hai endpoint đều có data.ok: true. Ghi riêng mục tiêu yêu cầu và phản hồi thực tế, không coi việc bấm nút là thành công. HTTP timeout nghĩa là chưa rõ kết quả; đừng hiển thị thành công đã xác nhận hoặc tự gửi thao tác ngược để sửa.

Tài liệu sự kiện mô tả conversation.updated với data.conversation.id và có thể có data.pinned khi trạng thái ghim thay đổi. Đây là trạng thái danh sách chat cục bộ của tài khoản đã kết nối, không cho biết tin nào được ghim trong cuộc trò chuyện.

Chỉ áp dụng cài đặt thực sự có trong sự kiện. Ví dụ, cập nhật tắt thông báo không có pinned không được xóa trạng thái ghim đã lưu. Xem sự kiện là dữ liệu quan sát, không phải bảo đảm mọi lệnh API đều có sự kiện xác nhận. Danh mục công khai hiện không có sự kiện riêng cho ghim tin nhắn, và ma trận sự kiện không ánh xạ conversation.updated cho LINE.

Khi nhận sự kiện, xác minh chữ ký và xử lý giao lặp theo hợp đồng giao Webhook. Sự kiện dùng để đồng bộ giao diện, không phải tự gọi lại cùng thao tác thay đổi.

Ghim không thay thế mức ưu tiên hỗ trợ

Giả sử một nhóm ghim chat trong lúc khách đang chờ trả lời. Đây là tình huống minh họa, không phải kết quả của khách hàng thực tế. Người phụ trách, hạn xử lý và trạng thái giải quyết vẫn phải nằm trong ứng dụng. Bỏ ghim không được âm thầm đóng phiếu hỗ trợ.

Đồng bộ đã đọc và chưa đọc cùng so sánh tắt thông báo và chặn cũng theo nguyên tắc này: mức độ dễ tìm, trạng thái đọc, tùy chọn thông báo và giới hạn liên hệ phục vụ các mục đích khác nhau.

Trước khi bật nút, nên kiểm tra ghim chat, thao tác bỏ ghim riêng, tin của thành viên nhóm khác, nền tảng không hỗ trợ và mất phản hồi HTTP. Đây là các kiểm tra đề xuất, không phải kết quả đã chạy. Nếu thao tác thủ công là đủ, hãy dùng ứng dụng gốc; nếu cần tích hợp chính thức, đánh giá hợp đồng đó riêng.

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

Ghim cuộc trò chuyện có ghim cả tin mới nhất không?

Không. Hai thao tác có đối tượng và API khác nhau.

Có thể dùng duration_seconds để ghim cuộc trò chuyện không?

Không theo hợp đồng hiện được UnifyPort công bố. Trường này thuộc thao tác ghim tin nhắn.

pinned trong conversation.updated có xác nhận ghim tin nhắn không?

Không. Nó mô tả cài đặt danh sách chat của tài khoản đã kết nối.

LINE có dùng được cả hai loại ghim qua UnifyPort không?

Ma trận hiện hỗ trợ ghim và bỏ ghim cuộc trò chuyện LINE, không hỗ trợ ghim tin nhắn. Cần kiểm tra từng thao tác.

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

Bắt đầu từ tài liệu ghim cuộc trò chuyện và đặt tên nút thể hiện rõ đối tượng trước khi bật chức năng.

Kiểm tra ngày 2026-10-08:

• WhatsApp: Nhắn tin cho chính mình
• WhatsApp: Ghim tin nhắn
• UnifyPort: Ghim và bỏ ghim tin nhắn
• UnifyPort: Hỗ trợ thao tác theo nền tảng