ログイン無料トライアルを開始
Meta Tech Provider

WhatsApp Webhook のステータス:sent、delivered、read、failed

ステータス Webhook は、WhatsApp Cloud API で企業が送信したメッセージの結果を報告します。messages フィールドで届き、messages 配列の代わりに statuses 配列を持ちます:sent(チェック 1 つ)、delivered(チェック 2 つ)、read(青いチェック 2 つ)、音声メッセージの played、そして errors 配列付きの failed です。statuses[].id を、送信リクエストが返した wamid と照合してください。

easyCoexistence は、既に使用している WhatsApp Business アプリの番号を、Coexistence を通じて Meta の Cloud API に接続します。

5

Meta が送信するステータス値は sent、delivered、read、played(音声メッセージの初回再生)、failed です。

3

1 件の送信メッセージから個別に届くことがあるステータス Webhook は、sent、delivered、read です。

v24.0

無料のエントリーポイント期間内のメッセージを除き、この Graph API バージョン以降は会話オブジェクトが省略されます。

0

過去の Webhook データを取得する API はありません。Meta は、ペイロードが届いたら取得して保存するよう求めています。

messages

転送されたステータスの X-EC-Event ヘッダー:ステータスは messages イベントに含まれ、value.statuses の下に置かれます。

WhatsApp のステータス Webhook はどこに届きますか?

顧客から届くメッセージと同じ messages フィールドに、同じ entry と changes の構造で届きます。違いは value の中にあります。受信メッセージは messages 配列を持ち、ステータスは statuses 配列を持ちます。value.messages だけを読むハンドラーは、エラーを出さずにすべてのステータスを捨ててしまいます。metadata.phone_number_id は、どの番号がメッセージを送信したかを示します。顧客のプロフィール名、wa_id、BSUID を含む contacts 配列も届きますが、failed ステータスとグループメッセージの sent ステータスには含まれません。以下は、Meta のサーバーから送信されたマーケティングテンプレートの例です:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

各ステータス値は何を意味しますか?

各値は、顧客が WhatsApp で見るマークに対応しています。read は、メッセージが配信された後にのみ数えられます。ただし、チャットが既に開いている状態でメッセージを受け取った場合、Meta は内部の最適化として、delivered の Webhook を送らずに read を送ります。そのため、トラッカーは delivered が届かなくても read を受け入れるべきです。また、固定された順序で一つずつ届くと想定するのではなく、ステータスに順位を付けて扱ってください。

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

ステータスオブジェクトはどのフィールドを持ちますか?

メッセージよりも少なく、いくつかは条件付きです。Meta のリファレンスには、各フィールドが存在する条件が次のように記載されています:

  • id:送信したメッセージの wamid。照合に使うキーです。
  • status と timestamp:値と、Webhook がトリガーされた Unix 時間(文字列)。
  • recipient_id:電話番号またはグループ ID。BSUID に送信し、番号が利用できない場合は省略されます。
  • recipient_user_id:顧客の BSUID。電話番号に送信した failed ステータスでは省略されます。
  • recipient_type と recipient_participant_id:グループ宛のメッセージのみ。
  • biz_opaque_callback_data:送信リクエストで設定した場合のみ。
  • pricing:sent と、delivered または read のいずれか一方のみ。errors:failed のみ。

ステータスを送信したメッセージとどう照合しますか?

wamid で照合します。送信リクエストは messages[0].id を返し、そのメッセージのすべてのステータスは statuses[].id に同じ値を持ちます。送信時にこの値を自分のレコードの横に保存し、ステータスが届いたら到達した最上位のステータスを保持しながら更新してください。遅れて届いた delivered が read を上書きしないようにするためです。wamid が分からないステータスは、オートメーションなど番号上の別の仕組みが送ったものなので、無視するかログに残してください。

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

Coexistence の番号では何が変わりますか?

ステータスは API 経由で送信された内容を表します。オートメーションからの返信、MCP コネクタ経由で AI が送ったメッセージ、自分のコードが送信したものが対象です。オーナーが WhatsApp Business アプリで入力した内容は、別の形でソフトウェアに届きます。これは smb_message_echoes として届き、Meta はアプリから送られたメッセージを映したものとして文書化しています。一度きりの履歴インポートで取り込まれたメッセージは、履歴 Webhook の中に独自のステータスを持ち、delivered、read、played、pending、error といった値になります。

ステータスは、その番号の messages フィールドが届く先ならどこにでも届きます。ダイレクトの送信先では、Meta は messages フィールドを送信先ごとに上書きできるため、ステータスをエンドポイントに直接送ります。オートメーションが有効で「Forward URL」が設定されている場合は、messages イベントとしてその URL に届きます。

AI やオートメーションは、メッセージが配信されたことをどう知りますか?

送信時ではなく、送信先を通じて知ります。アシスタントが send_template または send_message を呼び出すと、ツールの結果には wamid が含まれ、Meta がメッセージを受け付けたことが示されます。配信は後になって顧客のデバイス上で確認され、ステータスとして報告されます。easyCoexistence はクエリできるステータス履歴を保持せず、ステータスを読み取る MCP ツールもありません。そのため、配信確認が必要なエージェントは、自分のシステム経由で送信するか、「Forward URL」で受け取ったステータスを読んでください。

オートメーションも同様です。Runs タブの実行では、Meta がメッセージを受け付けた時点で返信ステップが完了と表示され、その後発生した失敗は、送信先に failed ステータスとしてのみ現れます。

よくある間違い

  • statuses という別のフィールドを探すこと。ステータスは messages で届くため、value.messages だけを読むハンドラーは、エラーなしにそれらを失います。
  • delivered を read より前に必須とすること。メッセージが届いた瞬間に既読になった場合、Meta は delivered の Webhook を省略します。
  • 送信レスポンスを配信とみなすこと。wamid は Meta がリクエストを受け付けたことを意味し、失敗は数分後に failed ステータスとして届くことがあります。
  • recipient_id だけで顧客を識別すること。BSUID に送信し電話番号が利用できない場合は省略されます。BSUID は recipient_user_id に入ります。
EasyCoexistence で実現する

オートメーション、AI、コードが送信した内容のステータスは、ダイレクトモードでは Meta から直接エンドポイントに届き、オートメーションが有効な場合は Forward URL に転送され X-EC-Signature で署名されます。デフォルトでは保存されません。料金は接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。

よくある質問

ステータス Webhook にメッセージ本文は含まれますか?

含まれません。ステータスには wamid、ステータス、宛先、タイムスタンプ、該当する場合は料金と errors が含まれます。ステータスと並べて表示する必要がある場合は、送信した内容のコピーを wamid をキーにして自分で保存してください。

後から Meta の過去のステータスを取得できますか?

できません。Meta の Webhook ガイドによれば、過去の Webhook データを取得する API はありません。そのため、エンドポイントが取得できなかったステータスは、Meta が最大 7 日間の再試行を止めた時点で失われます。

biz_opaque_callback_data は何のためのものですか?

送信時に設定する文字列で、自分の注文番号やチケット ID などを入れます。Meta はそのメッセージの statuses にこれを返すため、先に wamid を調べなくても、ステータスを自分のレコードと照合できます。

ステータス Webhook には 200 で応答する必要がありますか?

はい、他の Webhook の POST と同じです。Meta は 200 以外の応答を配信失敗とみなし、再試行します。同じステータスが二重に届く原因の一つはこれです。

続きを読む

WhatsApp メッセージが届かなかった理由:failed ステータスとエラーの読み方failed ステータスは、Meta が WhatsApp メッセージを送信も配信もできなかったことを示します。主なエラーコードと対処法を解説します。WhatsApp Webhook の料金オブジェクト:type、category、billable(2026 年)2026 年 10 月以降、WhatsApp のステータス Webhook に含まれる料金オブジェクトの内容と、課金の数え方を説明します。WhatsApp Webhook の再送、重複、順序:対処方法Meta は Webhook を最長 7 日間再送するため重複は起こり得ます。重複排除のキーと安全な処理方法を解説します。WhatsApp の通話 Webhook: Calling API のイベントと Coexistence 番号での通話calls フィールドは、接続、終了、通話ステータス、録音を報告します。実際のペイロードと Coexistence 番号での扱いを解説。WhatsApp のメッセージがサーバーに届く仕組み:直接か、マネージドか、署名の検証直接は Meta から自社サーバーへ。マネージドは自動応答と署名付き転送です。ペイロード、X-EC-Signature、再試行を解説します。WhatsApp ユーザー名と事業者スコープのユーザー ID(BSUID):Cloud API の Webhook で変わることユーザー名で変わる Cloud API の Webhook。BSUID、wa_id が省略される条件と Coexistence の変更点を解説します。

始める準備はできましたか?

WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。

無料トライアルを始める

確認日