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 に接続します。
Meta が送信するステータス値は sent、delivered、read、played(音声メッセージの初回再生)、failed です。
1 件の送信メッセージから個別に届くことがあるステータス Webhook は、sent、delivered、read です。
無料のエントリーポイント期間内のメッセージを除き、この Graph API バージョン以降は会話オブジェクトが省略されます。
過去の Webhook データを取得する API はありません。Meta は、ペイロードが届いたら取得して保存するよう求めています。
転送されたステータスの 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 のサーバーから送信されたマーケティングテンプレートの例です:
{
"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 を受け入れるべきです。また、固定された順序で一つずつ届くと想定するのではなく、ステータスに順位を付けて扱ってください。
ステータスオブジェクトはどのフィールドを持ちますか?
メッセージよりも少なく、いくつかは条件付きです。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 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 に入ります。
オートメーション、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 Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日