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_iddata.message.id→up_to_message_iddata.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"
}
再生では、2つのメッセージ対象フィールドがどちらも空でないことが必要です。仕様では、未知の通知種別、別チャネルでの再生指定、再生対象の欠落に対して 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音声再生を対象とします。LINEを併用する受信箱でも、共通APIという理由だけでLINE、Telegram、すべてのメディアへ拡張してはいけません。通知の取得は保証されず、再生や既読は内容の理解、同意、問い合わせ解決を証明しません。
FAQ
message.readなら音声は再生済みですか?
イベント名だけでは判断できません。data.event.receipt_type: "played" を確認します。
conversation_idだけで再生を報告できますか?
できません。会話に加え、メッセージIDと元の送信者IDが必要です。
playedは最後まで聞いた証拠ですか?
いいえ。定義されているのは再生開始であり、完了や聴取時間ではありません。
成功しても通常の既読になるのはなぜですか?
古いWhatsAppチャネルバージョンでは、そのように処理される場合があると仕様に記載されています。処理成功と実際の再生通知は別々に検証します。
次のステップと出典
会話の既読操作仕様に沿って管理下で再生開始フローを実装し、受信通知を別途確認してから再生バッジを有効にしてください。
製品資料の確認日:2026-11-20。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。