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

Вебхук messaging_referral в Instagram: ссылки ig.me и рекламные переходы

Поле вебхука messaging_referral в Instagram уведомляет приложение, когда человек, у которого уже есть переписка с профессиональным аккаунтом, открывает ссылку ig.me с параметром ref. Событие содержит объект referral верхнего уровня: ref, значение параметра; source, SHORTLINKS; и type, OPEN_THREAD. Если ref приходит в новой переписке, он передаётся внутри события messages или messaging_postbacks.

easyCoexistence подписывает каждый подключённый аккаунт Instagram на comments, messages и mentions, поэтому ref из первого сообщения новой переписки и реферал рекламы Click-to-Direct доходят до вашего HTTPS-эндпоинта внутри пересланного DM, подписанного секретом этого аккаунта.

2,083

Максимальное количество символов параметра ref в ссылке ig.me. Допустимы только буквы, цифры, дефисы, подчёркивания и знаки равенства.

OPEN_THREAD

Тип referral для ссылок ig.me. Реферал рекламы Click-to-Direct использует тот же тип, но с source ADS.

24 hours

Время, за которое приложение должно ответить после реферала в существующей переписке, что сбрасывает стандартное окно обмена сообщениями.

7 days

Как долго может действовать окно, открытое первым сообщением, отправленным после перехода по рекламе Click-to-Direct.

Instagram Web

Где ссылки ig.me не поддерживаются по данным руководства Meta по ig.me.

Когда срабатывает messaging_referral?

Когда человек, у которого уже есть переписка с профессиональным аккаунтом, открывает ссылку ig.me с параметром ref. Instagram открывает существующий диалог, и Meta отправляет реферал самостоятельно, без сообщения. Куда придёт реферал, зависит от переписки и от действий человека:

Existing threadmessaging_referral: a referral object beside sender, with no message.
New thread, ice breaker tappedmessaging_postbacks: postback.referral beside title and payload.
New thread, message typedmessages: message.referral beside mid.
Click-to-Direct admessages: message.referral with source ADS, ad_id and ads_context_data.

Как выглядит уведомление о реферале?

Событие messaging, в котором объект referral находится рядом с sender, recipient и timestamp, без сообщения и postback. Руководство Meta по ig.me приводит значения реферала внутри той же структуры, что и другие события Instagram messaging:

A messaging_referral notification
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "referral": {
            "ref": "<REF_PARAMETER_VALUE>",
            "source": "SHORTLINKS",
            "type": "OPEN_THREAD"
          }
        }
      ]
    }
  ]
}

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

Поля, которые Meta документирует для реферала ig.me, от внешних к внутренним:

  • sender.id: Instagram-scoped ID человека, который открыл ссылку. recipient.id и entry[].id: профессиональный аккаунт.
  • referral.ref: значение параметра ref из ссылки в том виде, в котором оно было передано.
  • referral.source: в примерах Meta для ig.me это SHORTLINKS. В одной таблице руководства Instagram Messaging написано SHORTLINK, а на странице примеров стоит заглушка.
  • referral.type: OPEN_THREAD, который Meta использует для рефералов ig.me.
  • timestamp: время срабатывания события; в примерах Meta указано в миллисекундах.

Как создать ссылку ig.me с ref?

В виде https://ig.me/<USERNAME>?ref=<VALUE>, где USERNAME это имя профессионального аккаунта, по руководству Meta Instagram Login; в руководстве Instagram Messaging записано https://ig.me/m/<USERNAME>. Параметр ref может содержать до 2 083 символов: буквы, цифры, дефисы, подчёркивания и знаки равенства. Meta советует использовать ref для отслеживания каналов, связи человека с сессией в другом приложении или перехода к конкретному контенту, а для новых переписок рекомендует ice breakers, каждый со своим ref.

Куда приходят рекламные рефералы?

В сообщения. Человек, который нажал рекламу, открывающую Instagram Direct и отправившую сообщение, создаёт событие messages, в котором message.referral содержит ref объявления (если он был задан), ad_id, source ADS, type OPEN_THREAD и ads_context_data с заголовком рекламы и photo_url или video_url, на который нажали. Страницы Instagram у Meta описывают messaging_referral только для ссылок ig.me.

A Click-to-Direct ad referral, inside messages
"message": {
  "mid": "<MESSAGE_ID>",
  "referral": {
    "ref": "<AD_REF_IF_SET>",
    "ad_id": "<AD_ID>",
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ads_context_data": {
      "ad_title": "<AD_TITLE>",
      "photo_url": "<IMAGE_URL_CLICKED>",
      "video_url": "<THUMBNAIL_URL_FOR_THE_AD_VIDEO>"
    }
  }
}

Открывает ли реферал окно для сообщений?

Да, в существующей переписке: руководство Meta по ig.me указывает, что реферал сбрасывает стандартное 24-часовое окно обмена сообщениями, поэтому приложение может ответить в течение 24 часов после события. Первое сообщение, отправленное после перехода по рекламе Click-to-Direct, может открыть окно длительностью до 7 дней с момента этого сообщения. Ответ отправляется через POST /<IG_ID>/messages с recipient.id, равным sender.id события.

Передаёт ли easyCoexistence рефералы?

Те, что передаются вместе с сообщениями. Каждый подключённый аккаунт подписан на comments, messages и mentions, поэтому ref из первого сообщения новой переписки и реферал рекламы Click-to-Direct доходят до вашего эндпоинта внутри пересланного DM как message.referral. messaging_referral для существующих переписок и messaging_postbacks для нажатий на ice breakers это отдельные поля, которые Meta доставляет приложению, подписанному на них.

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

  • Ожидание messaging_referral в новой переписке. Там ref приходит в messages или messaging_postbacks, в зависимости от того, написал ли человек сообщение или нажал ice breaker.
  • Использование других символов в ref. Meta принимает буквы, цифры, дефисы, подчёркивания и знаки равенства, до 2 083 символов.
  • Сверка source с одной точной строкой. В примерах Meta для ig.me стоит SHORTLINKS, для рекламы ADS, но одна таблица пишет SHORTLINK, поэтому ветвите логику по месту расположения реферала и по ref.
  • Проверка ссылок в Instagram Web. Meta не поддерживает ссылки ig.me там, поэтому открывайте их в приложении Instagram.
Настройка с EasyCoexistence

send_social_dm отвечает внутри 24-часового окна. От US$ 9 до US$ 0,75 за подключение в месяц, по мере добавления подключений; первые 3 дня бесплатно.

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

Что содержит referral.source в рефералах Instagram?

SHORTLINKS в примерах Meta для ig.me и ADS для рекламы Click-to-Direct, хотя одна таблица руководства Meta Instagram Messaging пишет SHORTLINK. Ветвите логику по месту расположения реферала и по ref, а не по одной точной строке.

Какой максимальной длины может быть параметр ref в ссылке ig.me?

До 2 083 символов, только буквы, цифры, дефисы, подчёркивания и знаки равенства.

Куда приходит ref ссылки ig.me в новой переписке Instagram?

В messages, если человек написал первое сообщение, или в messaging_postbacks, если он нажал ice breaker. messaging_referral относится только к существующим перепискам.

Работают ли ссылки ig.me в Instagram Web?

Нет. Руководство Meta по ig.me указывает, что они не поддерживаются в Instagram Web.

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

Вебхук Instagram messaging_postbacks: айсбрейкеры и кнопкиЧто отправляет вебхук messaging_postbacks Instagram при нажатии айсбрейкера, кнопки или пункта меню: title, payload, mid и как настроить.Вебхук сообщений Instagram: тело DM, эхо и поляЧто вебхук сообщений Instagram передаёт для DM: IGSID отправителя, текст, вложения, ответы на сторис и эхо, поле за полем, и окно 24 часа.Поля вебхуков Instagram: полный списокПоля вебхука, которые Meta перечисляет для Instagram API с Instagram Login: что запускает каждое, какое разрешение нужно и какие остались за Facebook Login.Instagram DM через API и 24-часовое окноКак работают личные сообщения Instagram через API: кому может писать аккаунт, окно 24 часа, приватные ответы и настройка «Allow access to messages».События вебхука Instagram: комментарии, упоминания и личные сообщения (DM)Как комментарии, упоминания и DM из Instagram доходят до вашего эндпоинта: что содержит каждое событие, как подписываются доставки и что проверить.

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

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

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

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