← 所有文章
教學

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 展開、重複傳遞及回執先於內容抵達的處理。播放應是獨立觀察紀錄,不應用最後抵達的事件覆蓋全部狀態;較晚抵達的一般已讀不能清除既有播放證據。

驗收檢查與限制

以下為建議測試,並非已完成的實測結果:

  1. 開啟對話或下載音訊,不送出播放回執。
  2. 確實開始播放時使用選取訊息及原傳送者,群組情境也一致。
  3. 缺少目標或渠道錯誤時,不進入重試迴圈。
  4. 請求成功不會自行建立「收到播放回執」的證據。
  5. 重複或批次播放回執只更新明確指定的訊息。
  6. 缺少 played_at 時保持未知;較晚的已讀不抹除播放紀錄。

UnifyPort 是非官方介面。此契約針對 WhatsApp 語音播放,不能因共用 API 就延伸到 LINE、Telegram 或所有媒體類型。回執不保證一定收到;播放或已讀也不表示理解內容、同意某項操作或客服案件已解決。

常見問題

message.read 就表示語音播放過嗎?

不能只看事件名稱。必須檢查 data.event.receipt_type: "played"。

只提供 conversation_id 可以回報播放嗎?

不行。除了對話目標,還需要訊息 ID 與原傳送者 ID。

played 能證明完整聽完嗎?

不能。文件定義的是開始播放,不是播放完成或實際收聽時間。

為什麼成功請求仍可能是一般已讀?

文件說明舊版 WhatsApp 渠道可能以一般已讀處理。請求成功與實際播放回執行為必須分開驗證。

下一步與來源

先依對話已讀操作文件實作一次受控的播放開始流程,再獨立驗證收到的回執,最後啟用播放標示。

產品資料核對日期:2026-11-20。

UnifyPort API

讓訊息接入變成一條穩定的產品管線。

先用統一 API 跑通傳送,再用標準事件把所有入站訊息接回業務系統。