Biên nhận phát tin nhắn thoại WhatsApp: phân biệt played và đã đọc
Để báo rằng tin nhắn thoại WhatsApp đã bắt đầu phát qua UnifyPort, hãy gọi thao tác đánh dấu đã đọc với receipt_type: "played", ID tin nhắn và ID người gửi gốc. Khi nhận biên nhận phát, kiểm tra data.event.receipt_type bên trong message.read. Biên nhận đã đọc thông thường không chứng minh âm thanh đã được phát; bắt đầu phát cũng không chứng minh người nhận đã nghe hết bản ghi.
Điểm chính
- Việc phát dùng thao tác đã đọc hiện có và sự kiện
message.read, không có endpoint hay tên sự kiện phát riêng. - Gửi biên nhận phát và nhận biên nhận phát là hai hướng bằng chứng khác nhau.
data.ok: truexác nhận yêu cầu đã được xử lý; phiên bản kênh WhatsApp cũ có thể xử lý thành đã đọc thông thường.- Lưu bằng chứng phát riêng với trạng thái đã đọc của hội thoại, trạng thái xử lý yêu cầu hỗ trợ và độ dài âm thanh.
Trước tiên, xác định phía đang xử lý
Tài liệu thao tác đánh dấu đã đọc quy định cách báo tin nhắn thoại WhatsApp bắt đầu phát. Tài liệu sự kiện chuẩn đặt biên nhận phát nhận được trong message.read.
| Tình huống | Cách xử lý đề xuất | Không được suy ra |
|---|---|---|
| Nhân viên mở hội thoại | Áp dụng quy tắc đã đọc thông thường của hộp thư | Tin nhắn thoại đã phát |
| Tin nhắn thoại đến được chọn thực sự bắt đầu phát | Cân nhắc gửi played cho tin nhắn đó | Nhân viên đã nghe hết |
| Nhận biên nhận phát của tin nhắn thoại đã gửi | Ghi nhận theo tin nhắn và người gửi biên nhận | Mọi thành viên đã nghe hoặc yêu cầu hỗ trợ đã giải quyết |
| Không nhận được biên nhận phát | Giữ trạng thái chưa xác nhận | Người nhận chắc chắn chưa phát |
Tín hiệu bắt đầu phát từ trình phát của ứng dụng là điểm kích hoạt đề xuất, không phải trường mới của UnifyPort. Không gửi biên nhận chỉ vì tệp đã tải xuống, dạng sóng đã hiển thị hoặc người dùng bấm nút nhưng âm thanh không phát. Quy tắc hàng đợi thông thường nằm trong hướng dẫn đồng bộ đã đọc/chưa đọc cho hộp thư chung.
Báo phát cho đúng tin nhắn đã chọn
Gọi POST /v1/accounts/{account_id}/conversations/read từ backend với X-Api-Key. Không đưa khóa xuống trình duyệt. Lưu cùng nhau các định danh từ một sự kiện tin nhắn đến:
account_idở cấp ngoài cùng;data.conversation.idthànhconversation_id;data.message.idthànhup_to_message_id;data.sender.idthànhup_to_message_sender_id.
Người gửi là tác giả tin nhắn gốc, không phải nhân viên đang nghe. Trong nhóm, đó cũng không phải ID nhóm. Sau khi bắt đầu phát, đừng lấy lại mục tiêu từ lựa chọn “tin nhắn mới nhất” có thể đã thay đổi.
Ví dụ nội dung yêu cầu sau dùng định danh giả định, không phải lưu lượng khách hàng được ghi lại:
{
"conversation_id": "100000000000002@lid",
"up_to_message_id": "VOICE_EXAMPLE_001",
"up_to_message_sender_id": "100000000000002@lid",
"receipt_type": "played"
}
Khi báo phát, cả hai trường mục tiêu tin nhắn phải có giá trị không rỗng. Tài liệu quy định 400 invalid_request với mã số 10000 cho loại biên nhận không hợp lệ, dùng played trên kênh khác hoặc thiếu mục tiêu phát. Hãy sửa đầu vào hoặc kênh thay vì tự động lặp lại yêu cầu.
Bỏ qua hoặc gửi loại biên nhận rỗng sẽ dùng ngữ nghĩa read thông thường, không thay thế cho việc chỉ định phát một cách rõ ràng. Với thao tác đọc WhatsApp thông thường, có thể bỏ cả hai trường mục tiêu để đánh dấu cả hội thoại; không áp dụng cách rút gọn đó cho yêu cầu phát.
Diễn giải thận trọng kết quả yêu cầu
data.ok: true cho biết xử lý yêu cầu thành công, không chứng nhận toàn bộ luồng biên nhận phát đã hoạt động. Tài liệu cảnh báo rõ rằng phiên bản kênh WhatsApp cũ có thể xử lý played như đã đọc thông thường. Không có số phiên bản tối thiểu được nêu tại đây, vì vậy không tự bổ sung.
Ứng dụng nên lưu mục tiêu đã chọn, hành động đã thử và kết quả quan sát được. Đây là bản ghi cục bộ, không phải trường API bổ sung. HTTP timeout khiến kết quả chưa xác định; không phải lý do để tuyên bố thất bại hay gửi lại một cách mù quáng. Kiểm tra bằng tài khoản nhắn tin do bạn kiểm soát trước khi hiển thị thông báo chắc chắn hơn “yêu cầu đã được xử lý”.
Nhận diện played trong message.read
Tài liệu message.read dùng data.event.receipt_type: "played" để biểu thị biên nhận phát. Thời điểm do nhà cung cấp báo, nếu có, nằm tại data.message.played_at. Nếu thiếu, không lấy read_at, thời điểm Webhook đến hoặc độ dài bản ghi để điền thay.
Hàm phân loại nhỏ dưới đây giả định sự kiện đã được xác thực và kiểm tra cấu trúc. Hàm không xác minh chữ ký hay lưu dữ liệu:
function isWhatsAppPlaybackReceipt(event) {
return event.provider === 'whatsapp' &&
event.type === 'message.read' &&
event.data?.event?.receipt_type === 'played';
}
Đăng ký message.read mà vẫn giữ các đăng ký đang cần. Tuân theo quy định giao Webhook: cấu hình signing_secret, kiểm tra HMAC-SHA256 trên X-Device-Timestamp, dấu chấm và phần thân thô, kiểm tra độ mới của timestamp, rồi lưu bền vững dữ liệu đã xác thực trước khi trả 2xx.
Biên nhận theo lô có thể chứa data.message.ids; nếu không, dùng data.message.id đơn lẻ. Giữ phạm vi workspace, nhà cung cấp, tài khoản, hội thoại và người gửi biên nhận. Hướng dẫn biên nhận đã giao và đã đọc theo lô giải thích cách mở rộng danh sách ID, xử lý trùng lặp và biên nhận đến trước nội dung. Thêm phát như một quan sát riêng, không thay toàn bộ trạng thái bằng sự kiện đến cuối. Biên nhận đọc thông thường đến muộn không được xóa bằng chứng phát trước đó.
Kiểm thử và giới hạn
Đây là các kiểm thử được đề xuất, không phải kết quả đã thực hiện:
- Mở hội thoại hoặc tải âm thanh không gửi biên nhận phát.
- Khi thực sự bắt đầu phát, dùng tin nhắn đã chọn và người gửi gốc, kể cả trong nhóm.
- Thiếu mục tiêu hoặc sai kênh không dẫn đến vòng lặp thử lại.
- Yêu cầu thành công không tự tạo bằng chứng đã nhận biên nhận phát.
- Biên nhận trùng lặp hoặc theo lô chỉ cập nhật những tin nhắn được chỉ định rõ.
- Thiếu
played_atthì thời điểm vẫn chưa biết; biên nhận đọc đến sau không xóa ghi nhận phát.
UnifyPort là giao diện không chính thức. Quy định này dành cho phát tin nhắn thoại WhatsApp, không tự áp dụng cho LINE, Telegram hay mọi loại phương tiện chỉ vì dùng chung API. Với hộp thư gồm WhatsApp và Zalo, vẫn phải kiểm tra khả năng từng kênh. Không có bảo đảm luôn nhận được biên nhận; phát hoặc đọc cũng không chứng minh đã hiểu nội dung, đã đồng ý hay đã giải quyết yêu cầu hỗ trợ.
Câu hỏi thường gặp
message.read có nghĩa là tin nhắn thoại đã phát không?
Không thể kết luận chỉ từ tên sự kiện. Cần kiểm tra data.event.receipt_type: "played".
Chỉ truyền conversation_id để báo phát được không?
Không. Ngoài hội thoại, còn cần ID tin nhắn và ID người gửi gốc.
played có chứng minh đã nghe hết bản ghi không?
Không. Thao tác được mô tả là báo bắt đầu phát, không phải hoàn tất hoặc thời lượng nghe thực tế.
Vì sao yêu cầu thành công vẫn có thể là đọc thông thường?
Tài liệu nêu rằng phiên bản kênh WhatsApp cũ có thể xử lý theo cách đó. Cần kiểm tra riêng việc xử lý yêu cầu và hành vi biên nhận phát quan sát được.
Bước tiếp theo và nguồn
Triển khai một luồng bắt đầu phát có kiểm soát theo tài liệu thao tác đã đọc, sau đó xác minh biên nhận đến một cách độc lập trước khi bật nhãn đã phát.
Đối chiếu tài liệu sản phẩm ngày 2026-11-20:
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.