Вебхук Instagram messaging_postbacks: айсбрейкеры и кнопки
Поле вебхука messaging_postbacks Instagram уведомляет приложение, когда человек нажимает вопрос-айсбрейкер, кнопку постбэка в шаблоне или пункт постоянного меню в переписке с профессиональным аккаунтом. Объект postback события содержит title, текст, который нажал человек; payload, строку, которую приложение задало для этого варианта; и mid, идентификатор сообщения, начиная с Graph API v11.0.
easyCoexistence подписывает каждый подключённый аккаунт Instagram на комментарии, сообщения и упоминания и пересылает эти события, включая нажатия быстрых ответов, на ваш HTTPS-эндпоинт по мере их поступления, подписанные секретом этого аккаунта и без хранения копий.
Максимум вопросов-айсбрейкеров, которые аккаунт может задать через Ice Breaker API Meta.
Версия Graph API, с которой события постбэка содержат mid; само поле требует v8.0 или новее.
Максимум кнопок в шаблоне с кнопками: каждая из них постбэк или web_url.
Время на ответ после нажатия пункта постоянного меню, которое открывает стандартное окно обслуживания клиентов.
Максимум быстрых ответов в одном сообщении; нажатый быстрый ответ приходит в messages, а не в messaging_postbacks.
Когда срабатывает messaging_postbacks?
Когда человек нажимает один из структурированных вариантов аккаунта в переписке, при условии, что приложение и аккаунт подписаны на это поле. Руководства Meta перечисляют такие источники:
- Вопрос-айсбрейкер, один из до 4, которые аккаунт предлагает при начале переписки. Недоступно в версии для компьютера.
- Кнопка постбэк в шаблоне кнопок, до 3 в сообщении, или в универсальном шаблоне, до 3 в каждом элементе.
- Пункт постбэка в постоянном меню аккаунта.
- Айсбрейкер, нажатый в новой переписке, открытой по ссылке ig.me с параметром ref: тогда постбэк также содержит referral.
- Тест самоотправки, когда аккаунт нажимает собственную кнопку: событие получает
is_selfсо значением true.
Как выглядит уведомление о постбэке?
Событие messaging, где вместо сообщения стоит объект postback. Пример Meta для Instagram Login содержит mid, title и payload, а руководство по айсбрейкерам показывает тот же объект без mid. Уведомление выглядит так:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}Что означает каждое поле?
Поля, которые Meta описывает для постбэка, от внешних к внутренним:
- sender.id: идентификатор в рамках Instagram того, кто нажал, на него нужно отвечать. recipient.id и entry[].id: профессиональный аккаунт.
- timestamp: когда человек нажал, по руководству Meta по айсбрейкерам.
- postback.title: вопрос-айсбрейкер или название кнопки, которое увидел человек.
- postback.payload: строка, заданная для этого варианта при создании, выбранная приложением.
- postback.mid: идентификатор сообщения, которое нажатие отправило аккаунту, начиная с Graph API v11.0.
- postback.referral: ref, source и type, когда переписка открыта по ссылке ig.me с параметром ref.
is_self: значение true рядом с postback, когда аккаунт нажимает собственную кнопку в тесте самоотправки.
Как настраиваются айсбрейкеры?
Запросом POST /<IG_ID>/messenger_profile на graph.instagram.com: platform со значением instagram и массив ice_breakers, в котором call_to_actions содержат до 4 пар вопрос и payload, с locale для каждого переведённого набора. GET /me/messenger_profile?fields=ice_breakers выводит их, а DELETE с fields, равным ice_breakers, удаляет. Выбранный здесь payload возвращается в messaging_postbacks при нажатии вопроса.
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}Как отправляются постбэк-кнопки?
Внутри сообщения, которое аккаунт отправляет запросом POST /<IG_ID>/messages. Шаблон кнопок содержит текст до 640 символов и от 1 до 3 кнопок; универсальный шаблон содержит до 10 элементов, в каждом до 3 кнопок. Кнопка типа postback возвращает свой payload в messaging_postbacks при нажатии, а кнопка web_url открывает страницу во встроенном браузере. Постоянное меню, задаваемое в messenger_profile, принимает те же два типа.
Используют ли быстрые ответы messaging_postbacks?
Нет: они приходят в messages. Нажатый быстрый ответ публикует свой текст в переписке как сообщение, и событие messages содержит text, равный этому тексту, и quick_reply.payload, равный payload этого варианта. Одно сообщение может предложить до 13 быстрых ответов по до 20 символов каждый, только простой текст. Руководство Meta по Instagram Messaging также перечисляет выбор айсбрейкера и универсального шаблона среди того, о чём сообщает messages, без примера payload.
Открывает ли нажатие окно переписки?
Для постоянного меню Meta это подтверждает: нажатие пункта меню открывает стандартное окно обслуживания клиентов, и на ответ у аккаунта есть 24 часа. Ответьте запросом POST /<IG_ID>/messages, указав recipient.id, равный sender.id постбэка. Ответ аккаунта возвращается в messages как echo, где is_echo равно true.
Передаёт ли easyCoexistence постбэки?
Только нажатия быстрых ответов. Они приходят в messages, на которые подписаны приложение easyCoexistence и каждый подключённый аккаунт, поэтому доходят до вашего эндпоинта с quick_reply.payload. Нажатия айсбрейкеров, кнопок и меню приходят в messaging_postbacks, на которое easyCoexistence не подписан, поэтому не пересылаются.
Распространённые ошибки
- Ожидание быстрых ответов в messaging_postbacks. Быстрый ответ приходит в messages, а quick_reply.payload находится рядом с текстом выбранного варианта.
- Маршрутизация по postback.title. Title это то, что увидел человек, и оно может отличаться по локали; маршрутизируйте по payload, который задаёт приложение.
- Ожидание mid на старой версии API. Meta включает postback.mid только начиная с Graph API v11.0.
- Задание более 4 айсбрейкеров или их тестирование на компьютере. Ice Breaker API Meta принимает до 4 вопросов, а эта функция недоступна в версии для компьютера.
send_social_dm отвечает человеку в пределах окна обслуживания клиентов (24 часа). От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений; первые 3 дня бесплатно.
Часто задаваемые вопросы
Какое поле вебхука сообщает о нажатиях айсбрейкеров Instagram?
messaging_postbacks. Объект postback содержит вопрос как title и заданный для него payload, а также mid из Graph API v11.0.
Сколько айсбрейкеров может быть у аккаунта Instagram?
До 4 вопросов, задаются запросом POST /<IG_ID>/messenger_profile с platform, равным instagram, при необходимости по locale.
Как ответить на постбэк Instagram?
Запросом POST /<IG_ID>/messages, указав recipient.id, равный sender.id постбэка, то есть идентификатору в рамках Instagram того, кто нажал. После нажатия пункта постоянного меню Meta даёт аккаунту 24 часа на ответ.
Маршрутизировать постбэки Instagram по title или по payload?
По payload, строке, которую приложение задало для варианта. Title это текст, который увидел человек, и он может отличаться по локали.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на