Вебхук сообщений Instagram: тело DM, эхо и поля
Поле сообщений вебхука Instagram передаёт личные сообщения профессионального аккаунта по мере их поступления: текст, вложения, публикации, ответы на сторис и упоминания, встроенные ответы и удаления. Каждое событие находится в массиве messaging с IGSID отправителя, получателем, временной меткой и объектом message. Сообщения, которые отправляет сам аккаунт, приходят в том же поле с is_echo, равным true.
easyCoexistence подписывает каждый подключённый аккаунт Instagram на messages и пересылает его DM, включая эхо, на ваш HTTPS-эндпоинт по мере поступления, подписывая секретом аккаунта; пересылка не сохраняет копию, а DM по умолчанию не хранятся.
Устанавливается в true в событии сообщения для сообщения, которое отправил сам аккаунт.
Стандартное окно обмена сообщениями для большинства действий пользователя, в течение которого приложение может ответить этому человеку.
Тип вложения для публикации, которой поделились; старый тип share поддерживался только до 1 февраля 2026 г.
Тип вложения события DM, которое Meta отправляет, когда кто-то упоминает аккаунт в своей сторис.
Подкод ошибки с кодом 200, когда владелец аккаунта отключил доступ к личным сообщениям Instagram.
Когда срабатывает поле messages?
Когда человек отправляет профессиональному аккаунту личное сообщение и когда аккаунт отправляет сообщение сам. Примеры и справочные материалы Meta перечисляют эти случаи; каждый из них является событием messaging с объектом message:
- Текст и медиа во вложениях: изображения, видео, аудио и файлы.
- Публикация или рилс, которым поделились, как вложение
ig_post,ig_reelили reel. - Ответ на сторис аккаунта с
reply_to.story и сторис, в которой упоминается аккаунт, как вложениеstory_mention. - Встроенный ответ на более раннее сообщение с
reply_to.mid и быстрый ответ сquick_reply.payload. - Сообщение, которое человек удалил (
is_deleted), неподдерживаемое медиа (is_unsupported) и сообщение от человека, который нажал на объявление Click-to-Direct (referral). - Сообщение, которое отправил аккаунт; оно приходит с
is_echo, равным true.
Как выглядит уведомление о сообщении?
POST-запрос, JSON которого содержит object со значением instagram. В отличие от комментария, сообщение находится в массиве messaging внутри entry аккаунта, и каждый элемент содержит sender, recipient, timestamp и message. Ответ на сторис аккаунта выглядит так:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}Что означает каждое поле?
Поля, которые Meta документирует для события сообщения в Instagram Login, от внешних к внутренним:
- entry[].id: ID профессионального аккаунта. entry[].time: когда Meta отправила уведомление; в примерах Meta сообщений оно указано в миллисекундах.
- sender.id и recipient.id: во входящем DM это IGSID человека и ID аккаунта; в эхо то же самое, но наоборот.
- timestamp: когда было отправлено сообщение; в примерах Meta указано в миллисекундах. Сортируйте сообщения по нему, а не по времени поступления.
- message.mid: ID сообщения для дедупликации, реакций и ответа на это сообщение через
reply_to.mid. - message.text: присутствует, когда сообщение содержит текст.
- message.attachments[]: каждый элемент с type и payload, обычно с url. Поле payload публикации
ig_postдобавляетig_post_media_idи title, то есть её подпись. - message.
reply_to: mid для встроенного ответа или story с url и id сторис для ответа на сторис. - message.
quick_reply.payload и message.referral: выбранный быстрый ответ и ref,ad_id, source, type иads_context_dataобъявления Click-to-Direct. - message.
is_deleted,is_echo,is_selfиis_unsupported: присутствуют, только когда имеют значение true. - message.
admin_textиhandoff_reason: в подходящих приложениях уведомление о том, что приложение Meta, например Meta Business Agent, передало диалог; может прийти без mid и text.
Как работают эхо?
Когда аккаунт отправляет сообщение, Meta также отправляет для него событие messages с is_echo, равным true. Тогда sender.id указывает на аккаунт, а recipient.id на IGSID человека. Тестовое сообщение, которое аккаунт отправляет самому себе, также содержит is_self. Эхо фиксируют то, что сказал аккаунт, и это нужно журналу диалогов, но обработчик, который решает, отвечать ли, должен их пропускать. Meta не отправляет эхо, когда аккаунт ставит реакцию на сообщение или убирает её.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}Какой ID использовать для ответа?
sender.id, IGSID человека. Meta создаёт его, когда кто-то пишет аккаунту или комментирует его медиа, и он относится к этому человеку и этому аккаунту. POST /<IG_ID>/messages с recipient.id, равным этому значению, отправляет ответ. Событие не содержит имени или имени пользователя; GET /<IGSID> с полями name и username возвращает их, поскольку человек, написавший аккаунту, уже дал согласие, необходимое для такого запроса.
Как сообщение открывает 24-часовое окно?
Приложение может написать человеку только после того, как тот написал аккаунту, и только в пределах стандартного окна обмена сообщениями, которое открывает его действие. Для большинства действий оно длится 24 часа, а после первого сообщения, отправленного после нажатия на объявление Click-to-Direct, до 7 дней. Новое сообщение от человека открывает новое окно, поэтому отслеживайте его последнюю временную метку. Эхо является собственным сообщением аккаунта и ничего не продлевает. Ответы, написанные человеком, могут использовать отдельное окно Meta Human Agent на 7 дней с тегом human_agent.
Чего не содержит событие messages?
Некоторых вещей, которые может искать обработчик, в событии нет, согласно справочным материалам Meta по сообщениям:
- Имени или имени пользователя человека: только IGSID, который преобразует GET /<IGSID>.
- Медиа для однократного просмотра: оно приходит как эфемерное вложение без URL.
- Точного изображения из карусели: реакция на одно изображение в публикации-карусели или пересылка такого изображения указывает на первое изображение.
- Реакций, правок и подтверждений прочтения: они приходят в собственных полях.
- Отметки о прочтении: сообщение, доставленное вебхуком, остаётся непрочитанным во входящих Instagram, пока не будет отправлен ответ.
Какие другие поля сообщений перечисляет Meta?
Поля и примеры Meta для Instagram Login, помимо messages, называют такие поля; каждое из них является отдельным событием messaging. easyCoexistence подписывает каждый аккаунт только на messages, comments и mentions, поэтому ни одно из них не входит в то, что сервис пересылает:
message_reactions: человек ставит реакцию на сообщение или убирает её; reaction.mid, action со значением react или unreact, а также reaction и emoji.message_edit: человек редактирует сообщение;message_edit.mid, новый текст иnum_edit.messaging_postbacks: человек нажимает кнопку стартового вопроса (icebreaker) или кнопку шаблона; postback.mid, title и payload.messaging_referral: человек, уже находящийся в диалоге, открывает ссылку ig.me с параметром ref.messaging_seen: человек читает сообщение; read.mid.messaging_optins,messaging_handoverи standby: последние два относятся к приложениям, которые делят диалог по протоколу передачи Meta.
Что должен включить аккаунт?
Разрешить доступ к сообщениям. Meta требует, чтобы профессиональный аккаунт включил эту опцию, прежде чем сообщениями можно будет управлять через API. Путь в приложении Instagram: «Настройки», «Сообщения и ответы на сторис», «Управление сообщениями», «Подключённые инструменты». Пока опция выключена, отправка завершается с ошибкой: код 200, подкод 2534041. Приложению также нужны instagram_business_basic и instagram_business_manage_messages, а для обслуживания аккаунтов, которыми оно не владеет и которые не администрирует, нужен Advanced Access.
Как easyCoexistence пересылает DM?
Так же, как комментарий: каждая запись, которую Meta доставляет для аккаунта, отправляется POST-запросом на ваш HTTPS-эндпоинт в конверте с полями platform, account_id, external_id и entry, подписанным в X-EC-Signature секретом аккаунта. Отправляется один раз, копия не сохраняется. Эхо пересылаются вместе с остальными, поэтому проверяйте is_echo перед ответом. Чтобы ответить, вызовите send_social_dm с account_id и sender.id события в качестве recipient_id в пределах 24-часового окна. Автоматизации, которые запускаются по DM, работают на тех же событиях.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}Распространённые ошибки
- Ответы на эхо. Событие с is_echo является собственным сообщением аккаунта, и ответ на него запускает цикл аккаунта с самим собой.
- Предположение, что в сообщении всегда есть текст. Вложения, публикации, упоминания в сторис и удаления приходят без поля text, поэтому ветвите логику по тому, что содержит объект message.
- Сортировка сообщений по времени поступления. После сбоя Meta может доставлять сообщения не по порядку, поэтому сортируйте их по timestamp.
- Разбор time и timestamp как секунд. В примерах Meta обе величины даны в миллисекундах; прочитанные как секунды, они дают даты в далёком будущем.
send_social_dm отвечает в пределах 24-часового окна, а автоматизации могут отвечать сами фиксированным текстом или с помощью ИИ. От US$ 9 до US$ 0,75 за подключение в месяц, с уменьшением по мере добавления подключений, с бесплатным пробным периодом на первые 3 дня.
Часто задаваемые вопросы
В секундах или миллисекундах приходят временные метки вебхуков сообщений Instagram?
В миллисекундах: в примерах Meta для сообщений это и timestamp, и время записи. Прочитанные как секунды, они превращаются в даты в далёком будущем.
Как получить имя отправителя из DM-вебхука Instagram?
Вызовите GET /<IGSID> с полями name и username. Событие содержит только IGSID человека.
Почему не приходят вебхуки DM из Instagram?
Проверьте, включена ли опция «Разрешить доступ к сообщениям», подписан ли аккаунт на messages через /subscribed_apps и находится ли приложение в режиме Live с Advanced Access для аккаунтов, которыми оно не владеет.
Пересылает ли easyCoexistence реакции на сообщения Instagram?
Нет. Реакции приходят в message_reactions, а easyCoexistence подписывает аккаунты только на messages, comments и mentions.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на