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 跑通發送,再用標準事件將所有入站訊息接返去業務系統。