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

Вебхук сообщений Instagram: тело DM, эхо и поля

Поле сообщений вебхука Instagram передаёт личные сообщения профессионального аккаунта по мере их поступления: текст, вложения, публикации, ответы на сторис и упоминания, встроенные ответы и удаления. Каждое событие находится в массиве messaging с IGSID отправителя, получателем, временной меткой и объектом message. Сообщения, которые отправляет сам аккаунт, приходят в том же поле с is_echo, равным true.

easyCoexistence подписывает каждый подключённый аккаунт Instagram на messages и пересылает его DM, включая эхо, на ваш HTTPS-эндпоинт по мере поступления, подписывая секретом аккаунта; пересылка не сохраняет копию, а DM по умолчанию не хранятся.

is_echo

Устанавливается в true в событии сообщения для сообщения, которое отправил сам аккаунт.

24 hours

Стандартное окно обмена сообщениями для большинства действий пользователя, в течение которого приложение может ответить этому человеку.

ig_post

Тип вложения для публикации, которой поделились; старый тип share поддерживался только до 1 февраля 2026 г.

story_mention

Тип вложения события DM, которое Meta отправляет, когда кто-то упоминает аккаунт в своей сторис.

2534041

Подкод ошибки с кодом 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. Ответ на сторис аккаунта выглядит так:

A messages notification, as Meta sends it
{
  "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 не отправляет эхо, когда аккаунт ставит реакцию на сообщение или убирает её.

An echo of a message the account sent
{
  "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, работают на тех же событиях.

A forwarded DM with an image
{
  "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 обе величины даны в миллисекундах; прочитанные как секунды, они дают даты в далёком будущем.
Настройка с EasyCoexistence

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.

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

Вебхук комментариев Instagram: полезная нагрузка поле за полемЧто вебхук комментариев Instagram присылает при комментарии к постам и Reels аккаунта: поля полезной нагрузки, чего в ней нет и ловушки.Верификация вебхуков Instagram: hub.challenge и X-Hub-Signature-256Как настроить вебхуки Instagram: ответить на hub.challenge, проверить X-Hub-Signature-256 секретом приложения, подписать каждый аккаунт и обработать повторы.События вебхука Instagram: комментарии, упоминания и личные сообщения (DM)Как комментарии, упоминания и DM из Instagram доходят до вашего эндпоинта: что содержит каждое событие, как подписываются доставки и что проверить.Instagram DM через API и 24-часовое окноКак работают личные сообщения Instagram через API: кому может писать аккаунт, окно 24 часа, приватные ответы и настройка «Allow access to messages».API приватных ответов в Instagram: ответ на комментарий личным сообщениемОтправьте приватный ответ в Instagram через API Meta: POST /<IG_ID>/messages с ID комментария, один на комментарий в течение 7 дней, ошибка 2534025.Упоминания в Instagram через API: поиск и ответы на @упоминанияКак @упоминания в Instagram приходят через API в вебхуке комментариев с Instagram Login и как на них отвечать в комментариях и подписях.

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

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

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

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