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

Вложения DM Instagram в вебхуке messages

Вебхук messages от Instagram передаёт медиа из DM в message.attachments: это массив объектов, у каждого есть type и payload, который обычно содержит url на CDN. Список Meta для Instagram Login включает image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story и устаревший share. Медиа однократного просмотра приходит как ephemeral-вложение без URL.

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

ig_post

Тип вложения для публикации, которой поделились. Его payload добавляет ig_post_media_id и title, подпись публикации, рядом с url.

1 Feb 2026

Когда старый тип вложения share перестал поддерживаться для публикаций Instagram, которыми поделились.

ephemeral

Тип исчезающих медиа однократного просмотра, которые приходят без URL.

is_unsupported

Принимает значение true в событии сообщения, если сообщение содержит неподдерживаемое медиа.

First image

Что сообщает уведомление, когда на одно изображение из карусели реагируют или его пересылают.

Какие типы вложений может нести событие DM?

Списки значений Meta для Instagram Login показывают эти значения message.attachments[].type, у каждого есть объект payload. Большинство payload содержит url к медиа в CDN Meta, а дополнительные поля payload Meta описывает только для ig_post, поэтому сначала читайте type, а потом payload.

imageA photo. Meta's Instagram Login list also puts GIFs and stickers under this type.
videoA video, at payload.url.
audioAudio, at payload.url.
fileA file, at payload.url.
ig_postA shared post: url, ig_post_media_id and title, its caption.
ig_reel and reelA shared Reel; Meta lists both names, each with a url.
story_mentionA Story that mentions the account, at its CDN URL.
shareThe legacy post share, supported until 1 February 2026.
media, story, ig_storyAlso in Meta's list, with no payload described.
ephemeralView-once media, sent with no URL.

Как выглядит DM с вложениями?

Это событие messages, в объекте message которого есть attachments вместо текста или вместе с ним. Пример Meta отправляет два медиафайла в одном сообщении, у каждого свой type и payload.url, поэтому обработчик должен перебирать массив, а не читать только первый элемент:

A DM with two attachments, 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>",
            "attachments": [
              { "type": "image", "payload": { "url": "<CDN_URL>" } },
              { "type": "video", "payload": { "url": "<CDN_URL>" } }
            ]
          }
        }
      ]
    }
  ]
}

Как выглядит публикация, которой поделились?

Это вложение ig_post. С 3 ноября 2025 года Meta передавала репосты публикаций и с вложением share, и с вложением ig_post. Share поддерживался для публикаций до 1 февраля 2026 года, а Meta заявляет, что новые интеграции должны поддерживать ig_post. Его payload добавляет ID медиа публикации и её подпись как title:

The attachment of a shared post
"attachments": [
  {
    "type": "ig_post",
    "payload": {
      "ig_post_media_id": "<MEDIA_ID>",
      "title": "<POST_CAPTION>",
      "url": "<CDN_URL>"
    }
  }
]

Что означает каждое поле?

Поля вложений, которые Meta описывает для события DM, от массива вниз:

  • message.attachments[]: один объект на каждый медиафайл; в примере Meta в одном сообщении два объекта.
  • type: что это за элемент, из списка выше. Сначала ветвитесь по нему, а потом читайте payload.
  • payload.url: URL к медиа в CDN. В обзоре Meta такие URL названы учитывающими приватность: они ничего не возвращают, когда контент удалён или истёк.
  • payload.ig_post_media_id и payload.title: только для ig_post, ID медиа публикации и её подпись.
  • message.text: присутствует, только если сообщение также содержит текст.
  • message.is_unsupported: true, когда сообщение содержит медиа, которое вебхук не поддерживает.

Сколько живут URL вложений?

Meta привязывает их к контенту. В обзоре сказано, что CDN-URL Instagram учитывают приватность и перестают возвращать медиа после удаления контента или истечения срока. Руководство Meta по упоминаниям в Stories говорит, что URL Story перестаёт работать, когда Story истекает или удаляется. Приложению, которому нужен файл, стоит получать его в момент прихода события и в рамках правил Meta: медиа Stories, например, нельзя сохранять или кэшировать.

Какие медиа вебхук не передаёт?

Руководство Meta по обмену сообщениями в Instagram называет эти пробелы. Обработчик должен ожидать их, а не считать ошибками:

  • Исчезающие медиа: однократный просмотр или запрет повтора. Это вложение типа ephemeral, без URL.
  • Неподдерживаемые медиа: сообщение приходит с is_unsupported, равным true.
  • GIF и стикеры: по этому руководству они не запускают вебхук, тогда как примеры Meta для Instagram Login относят их к image.
  • Выбранное изображение карусели: реакция на одно изображение в карусели или его пересылка сообщает первое изображение.
  • Публикации, которыми поделились, в целом: руководства Meta по сообщениям всё ещё говорят, что передаётся только URL медиа, хотя ig_post теперь добавляет ID медиа и подпись.

Как easyCoexistence передаёт вложения?

Без изменений, внутри entry: DM с медиа приходит на ваш эндпоинт с массивом attachments от Meta в том виде, в каком его отправила Meta, в конверте из platform, account_id, external_id и entry, с подписью X-EC-Signature. Вложения не скачиваются, а события по умолчанию не хранятся: аккаунт с включённой автоматизацией хранит текст DM, но не его медиа, 7 дней. Получайте нужные медиа по payload.url в момент прихода события и не храните медиа Stories.

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

  • Чтение только первого вложения. message.attachments это массив, а в примере Meta в одном сообщении два элемента, поэтому перебирайте весь массив.
  • По-прежнему сравнивают type со значением share для публикаций, которыми поделились. Meta поддерживала его для публикаций до 1 февраля 2026 года. Читайте ig_post, с ID медиа и подписью в payload.
  • Сохранение payload.url для последующей загрузки. URL перестаёт возвращать медиа после удаления или истечения контента, поэтому скачивайте нужное в момент получения, кроме медиа Stories.
  • Чтение payload.url без проверки type. Медиа однократного просмотра приходит как ephemeral без URL, а неподдерживаемое медиа ставит is_unsupported.
Настройка с EasyCoexistence

Пересылка подписана секретом этого аккаунта и не сохраняет копию, поэтому ваш агент или код получает нужные медиа. send_social_dm отвечает в пределах окна обслуживания клиентов (24 часа). От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, первые 3 дня бесплатно.

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

Можно ли сохранять медиа из вложения DM Instagram?

Скачивайте нужное в момент прихода события, так как payload.url перестаёт возвращать медиа после удаления или истечения контента. Исключение составляют медиа Stories: по правилам Meta их нельзя сохранять или кэшировать.

Почему у вебхука DM Instagram нет URL медиа?

Обычно это медиа однократного просмотра, которое приходит как ephemeral-вложение без URL, или неподдерживаемое медиа, из-за которого is_unsupported принимает значение true.

Запускают ли GIF и стикеры Instagram вебхук messages?

Документация Meta расходится: примеры Instagram Login относят GIF и стикеры к image, а руководство по обмену сообщениями в Instagram говорит, что для них вебхук не срабатывает. Проверьте на реальном аккаунте.

Может ли одно событие DM Instagram содержать несколько вложений?

Да. message.attachments это массив, а в примере Meta два медиафайла в одном сообщении.

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

Упоминания и ответы на сторис в вебхуке InstagramКак упоминания и ответы на сторис Instagram приходят в поле messages вебхука: вложение story_mention, reply_to.story, CDN-URL и окно ответа.Вебхук сообщений Instagram: тело DM, эхо и поляЧто вебхук сообщений Instagram передаёт для DM: IGSID отправителя, текст, вложения, ответы на сторис и эхо, поле за полем, и окно 24 часа.Вебхук message_reactions в Instagram: тело запроса при реакции и снятии реакцииЧто вебхук message_reactions Instagram отправляет, когда человек ставит реакцию на личное сообщение или убирает её: mid, action, reaction и emoji.Поля вебхуков Instagram: полный списокПоля вебхука, которые Meta перечисляет для Instagram API с Instagram Login: что запускает каждое, какое разрешение нужно и какие остались за Facebook Login.Instagram DM через API и 24-часовое окноКак работают личные сообщения Instagram через API: кому может писать аккаунт, окно 24 часа, приватные ответы и настройка «Allow access to messages».

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

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

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

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