← 全記事
チュートリアル

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"
}

再生では、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展開、重複、本文より先に届く通知を扱っています。再生は独立した観測として追加し、最後に届いたイベントですべての状態を置き換えないでください。遅れて届いた通常の既読で再生の証拠を消してはいけません。

確認項目と制約

以下は提案するテストであり、実施済みの結果ではありません。

  1. 会話を開く、音声をダウンロードするだけでは再生通知を送らない。
  2. 実際の再生開始で選択メッセージと元の送信者を使う。グループでも同様。
  3. 対象欠落やチャネル違いで再試行ループに入らない。
  4. リクエスト成功から受信再生通知を自動生成しない。
  5. 重複やバッチ通知は明示された対象だけを更新する。
  6. 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。

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。