ログイン無料トライアルを開始
easyCoexistence 公式 API

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 エンドポイントへ転送します。

5 seconds

Meta が Messenger の Webhook エンドポイントに、各通知へ 200 OK で応答するまでの制限時間。

1 hour

この期間を超えて配信が失敗すると、Meta は再購読されるまで、アプリを Page の Webhook から購読解除します。

PSID

messages イベントにある送信者の Page スコープ ID。ユーザーと Page の組み合わせごとに一意です。

Workplace only

Meta のリファレンスにおける mention イベントの sender フィールドの扱い。

No history

過去の Webhook 通知は後から照会できないため、受信側は必要な情報を保存しておく必要があります。

messages フィールドは何を送信しますか?

ユーザーが Page に Messenger メッセージを送ると通知されます。Meta は、テキストメッセージや、画像、音声、動画、ファイル、スタンプなどの添付ファイル付きメッセージを送信します。共有リンクは、代替の添付ファイルとして届くこともあります。以前のメッセージへの返信には、そのメッセージの mid を指す reply_to が含まれ、クイック返信にはそのペイロードが含まれます。

messages イベントはどのような形式ですか?

フィードの変更とは異なり、メッセージは Page の entry 内の messaging 配列で届きます。各イベントには、ユーザーの Page スコープ ID である sender、Page である recipient、タイムスタンプ、そして message があります。message には mid とテキストが含まれ、または type と payload URL を持つ attachments が含まれます:

A messages event, as Meta sends it
{
  "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 として受け取る値です:

A forwarded messages event
{
  "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 分を超えて古いタイムスタンプは拒否してください。

Node.js: verifying X-EC-Signature
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 をキーにしてください。
EasyCoexistence で実現する

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 監視

確認日