Facebook Page 向け Messenger Webhook: メッセージとメンションのイベント
Facebook Page 向け Webhook の messages フィールドは、ユーザーが Page に Messenger メッセージを送ったときに発火します。messaging 配列で、送信者の Page スコープ ID、Page の ID、タイムスタンプ、メッセージの mid、テキストまたは添付ファイルが届きます。mention フィールドは、投稿やコメントで Page がメンションされた新着を報告します。Meta は両方に X-Hub-Signature-256 で署名します。
easyCoexistence は、接続済みの各 Page の Messenger メッセージとメンションを、届き次第 HTTPS エンドポイントへ転送します。
Meta が Messenger の Webhook エンドポイントに、各通知へ 200 OK で応答するまでの制限時間。
この期間を超えて配信が失敗すると、Meta は再購読されるまで、アプリを Page の Webhook から購読解除します。
messages イベントにある送信者の Page スコープ ID。ユーザーと Page の組み合わせごとに一意です。
Meta のリファレンスにおける mention イベントの sender フィールドの扱い。
過去の Webhook 通知は後から照会できないため、受信側は必要な情報を保存しておく必要があります。
messages フィールドは何を送信しますか?
ユーザーが Page に Messenger メッセージを送ると通知されます。Meta は、テキストメッセージや、画像、音声、動画、ファイル、スタンプなどの添付ファイル付きメッセージを送信します。共有リンクは、代替の添付ファイルとして届くこともあります。以前のメッセージへの返信には、そのメッセージの mid を指す reply_to が含まれ、クイック返信にはそのペイロードが含まれます。
messages イベントはどのような形式ですか?
フィードの変更とは異なり、メッセージは Page の entry 内の messaging 配列で届きます。各イベントには、ユーザーの Page スコープ ID である sender、Page である recipient、タイムスタンプ、そして message があります。message には mid とテキストが含まれ、または type と payload URL を持つ attachments が含まれます:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}mention フィールドは何を送信しますか?
Page が投稿またはコメントでメンションされると、field が mention の変更が届きます。post_id または comment_id、メッセージ、リンク、写真、動画のいずれか、さらに item と verb が含まれます。Meta は、権限不足やプライバシーの理由から、一部の投稿 ID やコメント ID は照会できないことがあると注意しています。また、リファレンスでは sender フィールドは Workplace 専用とされているため、メンションが作成者の情報なしで届く場合があります。
転送されない Messenger フィールドはどれですか?
easyCoexistence は Page を messages には購読しますが、message_echoes、messaging_postbacks、message_reads、message_deliveries には購読しません。そのため、Page が送信したメッセージ、ボタンのタップ、既読や配信の通知は転送されません。send_social_dm で送った返信は、代わりに独自のメッセージ ID を返します。
イベントはエンドポイントにどう届きますか?
Meta は Page の Webhook を、Page がインストールしたアプリに、アプリ全体で 1 つのコールバック URL を通じて配信します。easyCoexistence は配信ごとに Meta の X-Hub-Signature-256 を検証し、すぐに Meta へ応答します。接続済みの Page ごとの各 entry は、その Page 用に設定した HTTPS エンドポイントへ、その Page 専用のシークレットで署名して転送します。設定は Claude または ChatGPT から set_social_webhook_destination を使うか、Partner API の PUT /channels/:id/webhook で行えます。シークレットは一度だけ表示され、再度設定すると新しいものが発行されます。URL を null にすると転送が止まります。
転送されたイベントはどのような形式ですか?
platform、Page の接続に対して list_social_accounts が返す account_id、Page の ID である external_id、そして Page 向けの Meta の entry(変更なし)を含む POST が届きます。sender.id は、24 時間以内の返信で send_social_dm が recipient_id として受け取る値です:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}転送されたイベントを検証するにはどうすればよいですか?
転送される各 POST には X-EC-Signature ヘッダーが付き、形式は t=<unix>,v1=<hex> です。v1 は、タイムスタンプ、ドット、そして生のボディを連結したものの HMAC-SHA256 で、Page の署名用シークレットを鍵とします。受信したとおりのボディ全体で計算し、定数時間で比較してください。5 分を超えて古いタイムスタンプは拒否してください。
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}配信は再試行されますか?
easyCoexistence では再試行されません。各 entry は一度だけメモリ上で転送され、再試行用のコピーは保持されません。転送は 8 秒間応答を待ち、リダイレクトには従わず、パブリック IP に解決される HTTPS アドレスにのみ送信します。Meta は、過去の通知は後から照会できないと注意しているため、届いた時点で必要な情報を保存してください。上流では、Meta が失敗した配信を短時間に数回再試行するため、同じメッセージが稀に 2 回届くことがあります。mid で重複を排除してください。
よくある間違い
- 応答前に処理をしてしまうこと。転送は再試行されないため、2xx をすぐに返し、イベントの処理は後で行ってください。
- 解析済みの JSON で署名を検証すること。HMAC は、届いたとおりの生のボディ全体で計算してください。
- メッセージには常にテキストがあると想定すること。スタンプ、画像、共有リンクは attachments として届き、text フィールドはありません。
- 重複排除を省くこと。失敗後に Meta が同じイベントを再配信することがあるため、処理の前にメッセージの mid をキーにしてください。
Page ごとのシークレットで署名し、コピーは保持しません。send_social_dm は 24 時間以内の返信に使えます。転送は set_social_webhook_destination または Partner API で有効にできます。料金は接続 1 件あたり月額 US$ 9 から US$ 0.75 まで、接続を増やすほど下がります。最初の 3 日間は無料トライアルです。
よくある質問
easyCoexistence は Page をどの Webhook フィールドに購読させますか?
Messenger 用の messages と、メンション用の mention です。Page の投稿とコメント用の feed も購読します。
Messenger のスタンプや画像にはテキストが付いてきますか?
いいえ。スタンプ、画像、共有リンクは attachments で届き、それぞれに type と payload URL があります。message にはテキストフィールドがありません。
Messenger の Webhook エンドポイントは、どれくらいの速さで応答する必要がありますか?
5 秒以内に 200 OK を返してください。配信が 1 時間失敗し続けると、Meta はアプリを Page の Webhook から購読解除します。
転送されたメッセージに返信するにはどうすればよいですか?
send_social_dm を呼び出し、イベントの sender.id を recipient_id として指定してください。ユーザーのメッセージから 24 時間以内に行う必要があります。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日