ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Вебхук Messenger для Facebook Page: сообщения и упоминания

Поле messages в вебхуках Facebook Page срабатывает, когда человек отправляет Странице сообщение в Messenger. Оно передаёт массив messaging с Page-scoped ID отправителя, ID Страницы, временной меткой и mid сообщения с его текстом или вложениями. Поле mention сообщает о новых упоминаниях Страницы в публикациях и комментариях. Meta подписывает оба вида уведомлений заголовком X-Hub-Signature-256.

easyCoexistence пересылает сообщения Messenger и упоминания каждой подключённой Страницы на ваш HTTPS-эндпоинт по мере поступления, подписанные секретом этой Страницы и без сохранённой копии.

5 seconds

Как быстро эндпоинт вебхука Messenger должен ответить 200 OK на каждое уведомление Meta.

1 hour

Если доставка не удаётся в течение этого времени, Meta отписывает приложение от вебхуков Facebook Page, пока оно не подпишется снова.

PSID

Page-scoped ID отправителя в событии messages, уникальный для каждой пары «человек и Страница».

Workplace only

Как справочник Meta описывает поле sender в событии упоминания.

No history

Прошлые уведомления вебхука нельзя запросить позже, поэтому получатель должен сохранять всё необходимое.

Что отправляет поле messages?

Уведомление о том, что человек отправил Странице сообщение в Messenger. Meta передаёт текстовые сообщения и сообщения с вложениями: изображениями, аудио, видео, файлами, стикерами и другими типами. Ссылка может прийти запасным вложением. Ответ на более раннее сообщение содержит reply_to с mid этого сообщения, а быстрый ответ содержит свой payload.

Как выглядит событие messages?

В отличие от изменений ленты, сообщение приходит в массиве messaging внутри entry Страницы. Каждое событие содержит sender, Page-scoped ID человека; recipient, Страницу; timestamp, временную метку; и message с его mid и текстом либо attachments с типом и URL payload:

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?

Изменение с полем mention, когда Страницу упоминают в публикации или комментарии. Оно содержит post_id или comment_id, текст сообщения, ссылку, фото или видео при наличии, а также item и verb. Meta предупреждает, что некоторые ID публикаций и комментариев нельзя запросить из-за отсутствия разрешения или по соображениям конфиденциальности. Справочник Meta указывает, что поле sender относится только к Workplace, поэтому упоминание может прийти без автора.

Какие поля Messenger не передаются?

easyCoexistence подписывает Страницы на messages, но не на message_echoes, messaging_postbacks, message_reads или message_deliveries, поэтому сообщения, отправленные самой Страницей, нажатия кнопок и подтверждения прочтения или доставки не передаются. Ответ, отправленный через send_social_dm, возвращает собственный ID сообщения.

Как события попадают на ваш эндпоинт?

Meta доставляет вебхуки Страницы приложению, которое Страница установила, через один callback URL для всего приложения. easyCoexistence проверяет заголовок X-Hub-Signature-256 каждой доставки, сразу отвечает Meta и пересылает каждую запись для подключённой Страницы на HTTPS-эндпоинт, который вы для неё указали, подписанный собственным секретом этой Страницы. Задайте его через set_social_webhook_destination из Claude или ChatGPT либо через PUT /channels/:id/webhook в Partner API. Секрет показывается один раз, повторная установка выпускает новый, а URL со значением null отключает пересылку.

Как выглядит переданное событие?

POST, который содержит platform, account_id, который list_social_accounts возвращает для подключения Страницы, ID Страницы в поле external_id и entry: entry Meta для Страницы без изменений. sender.id является recipient_id, который send_social_dm принимает для ответа в пределах 24-часового окна:

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 от временной метки, точки и исходного тела, с ключом, которым служит секрет подписи Страницы. Вычислите подпись по телу ровно в том виде, в котором оно пришло, сравните за постоянное время и отклоните временную метку старше 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 не повторяет доставку. Каждая запись пересылается один раз, в памяти, без сохранённой копии для повтора. Пересылка ждёт ответа 8 секунд, не следует перенаправлениям и отправляется только на HTTPS-адрес, который разрешается в публичный IP. Meta отмечает, что прошлые уведомления нельзя запросить позже, поэтому сохраняйте нужное по мере поступления. На стороне Meta при сбое доставка повторяется несколько раз подряд, поэтому одно и то же сообщение иногда может прийти дважды: отбрасывайте дубликаты по его mid.

Распространённые ошибки

  • Работа до ответа. Пересылка не повторяется, поэтому сразу возвращайте 2xx, а событие обрабатывайте после.
  • Проверка подписи по разобранному JSON. Вычисляйте HMAC по исходному телу ровно в том виде, в котором оно пришло.
  • Предположение, что в сообщении всегда есть текст. Стикер, изображение или ссылка приходят во вложениях, и поля text в них нет.
  • Пропуск дедупликации. Meta может доставить событие повторно после сбоя, поэтому перед действием проверяйте его по mid сообщения.
Настройка с EasyCoexistence

send_social_dm отвечает в пределах 24-часового окна. Включите пересылку через set_social_webhook_destination или Partner API. От US$ 9 до US$ 0,75 за подключение в месяц, по мере добавления подключений цена снижается, первые 3 дня бесплатно.

Часто задаваемые вопросы

На какие поля вебхуков easyCoexistence подписывает Страницу?

messages для Messenger и mention для упоминаний, а также feed для публикаций и комментариев Страницы.

Есть ли текст у стикера или изображения в Messenger?

Нет. Стикер, изображение или ссылка приходят во вложениях, у каждого есть тип и URL payload, а поля text в сообщении нет.

За какое время эндпоинт вебхука Messenger должен ответить?

Ответом 200 OK в течение 5 секунд. Если доставки не удаются в течение 1 часа, Meta отписывает приложение от вебхуков Страницы.

Как ответить на переданное сообщение?

Вызовите send_social_dm, передав sender.id из события как recipient_id, в течение 24 часов после сообщения человека.

Читайте дальше

Вебхук ленты Facebook Страницы: события комментариев, публикаций и реакцийЧто передаёт вебхук ленты Facebook Страницы при комментариях, публикациях и реакциях: поля item и verb, структура тела запроса Meta и подписка Страницы.Окно 24 часа в Messenger: когда страница Facebook может написать человекуКогда страница Facebook может написать человеку в Messenger: стандартное окно 24 часа, действия, которые его открывают, и до 7 дней после рекламы.API приватных ответов Facebook: написать тому, кто прокомментировал СтраницуОтправьте приватный ответ через API Meta: POST /{page-id}/messages с ID комментария, одно сообщение в Messenger в течение 7 дней, а также ошибки.Разрешения Facebook Page API и требования App ReviewДевять разрешений Facebook Page, что открывает каждое и что App Review требует: расширенный доступ, верификация бизнеса, запись экрана.Токен доступа к странице Facebook: как долго он действует и что его аннулируетКак получить токен доступа к странице Facebook без срока действия, кто может его получить и что заставляет Meta перестать его принимать.Ошибка Facebook 551: человек недоступен в MessengerОшибка Facebook 551: Messenger не смог доставить сообщение. Человек мог заблокировать Страницу или деактивировать аккаунт.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на