Вебхук Messenger для Facebook Page: сообщения и упоминания
Поле messages в вебхуках Facebook Page срабатывает, когда человек отправляет Странице сообщение в Messenger. Оно передаёт массив messaging с Page-scoped ID отправителя, ID Страницы, временной меткой и mid сообщения с его текстом или вложениями. Поле mention сообщает о новых упоминаниях Страницы в публикациях и комментариях. Meta подписывает оба вида уведомлений заголовком X-Hub-Signature-256.
easyCoexistence пересылает сообщения Messenger и упоминания каждой подключённой Страницы на ваш HTTPS-эндпоинт по мере поступления, подписанные секретом этой Страницы и без сохранённой копии.
Как быстро эндпоинт вебхука Messenger должен ответить 200 OK на каждое уведомление Meta.
Если доставка не удаётся в течение этого времени, Meta отписывает приложение от вебхуков Facebook Page, пока оно не подпишется снова.
Page-scoped ID отправителя в событии messages, уникальный для каждой пары «человек и Страница».
Как справочник Meta описывает поле sender в событии упоминания.
Прошлые уведомления вебхука нельзя запросить позже, поэтому получатель должен сохранять всё необходимое.
Что отправляет поле messages?
Уведомление о том, что человек отправил Странице сообщение в Messenger. Meta передаёт текстовые сообщения и сообщения с вложениями: изображениями, аудио, видео, файлами, стикерами и другими типами. Ссылка может прийти запасным вложением. Ответ на более раннее сообщение содержит reply_to с mid этого сообщения, а быстрый ответ содержит свой payload.
Как выглядит событие messages?
В отличие от изменений ленты, сообщение приходит в массиве messaging внутри entry Страницы. Каждое событие содержит sender, Page-scoped ID человека; recipient, Страницу; timestamp, временную метку; и message с его mid и текстом либо attachments с типом и URL payload:
{
"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-часового окна:
{
"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 минут.
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 сообщения.
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 часов после сообщения человека.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на