WhatsApp 語音播放回執:區分 played 與已讀
透過 UnifyPort 回報 WhatsApp 語音開始播放,請呼叫對話已讀操作,傳入 receipt_type: "played"、訊息 ID 與原始傳送者 ID。接收播放回執時,則檢查 message.read 裡的 data.event.receipt_type。一般已讀不是播放證據;開始播放也不代表對方已完整聽完錄音。
重點
- 播放沿用既有已讀操作與
message.read,不是另一個端點或事件名稱。 - 送出播放回執與收到播放回執,是不同方向的證據。
data.ok: true代表請求已處理;舊版 WhatsApp 渠道可能當成一般已讀處理。- 播放紀錄應與對話已讀、客服案件解決狀態及音訊長度分開保存。
先釐清你處理的是哪一側
對話已讀操作文件定義如何回報 WhatsApp 語音開始播放;標準事件文件則將收到的播放回執放在 message.read 中。
| 情境 | 建議處理 | 不可推論 |
|---|---|---|
| 客服開啟對話 | 套用一般收件匣已讀規則 | 語音已播放 |
| 選取的收到語音確實開始播放 | 為該訊息回報 played | 客服已聽完 |
| 已傳送語音收到播放回執 | 依訊息與回執傳送者記錄播放 | 全部成員都聽過,或案件已解決 |
| 未收到播放回執 | 維持未確認 | 對方一定沒有播放 |
應用程式播放器的「開始播放」訊號是建議觸發點,不是 UnifyPort 的新欄位。只下載檔案、顯示波形,或按下播放卻未成功啟動,都不應送出請求。一般客服佇列規則請參考共用收件匣已讀/未讀同步。
為選取的訊息回報播放
由後端使用 X-Api-Key 呼叫 POST /v1/accounts/{account_id}/conversations/read,不要將金鑰放進瀏覽器。一起保存同一則收到事件的識別資訊:
- 頂層
account_id; data.conversation.id對應conversation_id;data.message.id對應up_to_message_id;data.sender.id對應up_to_message_sender_id。
傳送者是原訊息作者,不是播放語音的客服。在群組中,它也不是群組 ID。播放開始後,不要再從可能改變的「最新訊息」選取狀態讀取目標。
以下請求本文使用虛構識別碼,並非擷取的客戶流量:
{
"conversation_id": "100000000000002@lid",
"up_to_message_id": "VOICE_EXAMPLE_001",
"up_to_message_sender_id": "100000000000002@lid",
"receipt_type": "played"
}
播放要求兩個訊息目標欄位都不可為空。文件指出,未知回執類型、其他渠道使用播放類型,或缺少播放目標時,回傳 400 invalid_request,數值代碼為 10000。應修正輸入或渠道,不要自動重複請求。
省略或傳入空的回執類型會採用一般 read 語義,不能代替明確選擇播放。一般 WhatsApp 已讀可同時省略兩個目標欄位,標記整個對話;播放請求不能沿用這項簡化方式。
保守解讀請求結果
data.ok: true 表示請求處理成功,不等於端到端播放回執已驗證。文件明確提醒,舊版 WhatsApp 渠道可能將 played 當作一般已讀處理。此處沒有提供最低版本號,不應自行補上。
應用程式可記錄選取目標、嘗試的動作及觀察結果;這些是本地紀錄,不是新增 API 欄位。HTTP 逾時表示結果不確定,不應直接宣告失敗或盲目重試。先使用自己控制的通訊帳號驗證行為,再決定能否顯示比「請求已處理」更強的成功提示。
在 message.read 中辨識 played
message.read 文件以 data.event.receipt_type: "played" 表示播放回執。可選的平台播放時間位於 data.message.played_at;若未提供,不要以 read_at、Webhook 抵達時間或錄音長度代填。
以下分類函式假設事件已完成驗證及結構檢查,不負責驗證簽章或寫入儲存空間:
function isWhatsAppPlaybackReceipt(event) {
return event.provider === 'whatsapp' &&
event.type === 'message.read' &&
event.data?.event?.receipt_type === 'played';
}
訂閱 message.read 時保留原有訂閱。遵循 Webhook 傳遞契約:設定 signing_secret,對 X-Device-Timestamp、一個點與原始本文計算 HMAC-SHA256,檢查時間戳是否過舊,並在通過驗證的事件持久化後回覆 2xx。
批次回執可能包含 data.message.ids,否則使用單一 data.message.id。比對時保留工作空間、渠道、帳號、對話及回執傳送者範圍。批次送達與已讀回執指南說明了 ID 展開、重複傳遞及回執先於內容抵達的處理。播放應是獨立觀察紀錄,不應用最後抵達的事件覆蓋全部狀態;較晚抵達的一般已讀不能清除既有播放證據。
驗收檢查與限制
以下為建議測試,並非已完成的實測結果:
- 開啟對話或下載音訊,不送出播放回執。
- 確實開始播放時使用選取訊息及原傳送者,群組情境也一致。
- 缺少目標或渠道錯誤時,不進入重試迴圈。
- 請求成功不會自行建立「收到播放回執」的證據。
- 重複或批次播放回執只更新明確指定的訊息。
- 缺少
played_at時保持未知;較晚的已讀不抹除播放紀錄。
UnifyPort 是非官方介面。此契約針對 WhatsApp 語音播放,不能因共用 API 就延伸到 LINE、Telegram 或所有媒體類型。回執不保證一定收到;播放或已讀也不表示理解內容、同意某項操作或客服案件已解決。
常見問題
message.read 就表示語音播放過嗎?
不能只看事件名稱。必須檢查 data.event.receipt_type: "played"。
只提供 conversation_id 可以回報播放嗎?
不行。除了對話目標,還需要訊息 ID 與原傳送者 ID。
played 能證明完整聽完嗎?
不能。文件定義的是開始播放,不是播放完成或實際收聽時間。
為什麼成功請求仍可能是一般已讀?
文件說明舊版 WhatsApp 渠道可能以一般已讀處理。請求成功與實際播放回執行為必須分開驗證。
下一步與來源
先依對話已讀操作文件實作一次受控的播放開始流程,再獨立驗證收到的回執,最後啟用播放標示。
產品資料核對日期:2026-11-20。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。