Вебхук 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, подписанного секретом этого аккаунта.
Максимальное количество символов параметра ref в ссылке ig.me. Допустимы только буквы, цифры, дефисы, подчёркивания и знаки равенства.
Тип referral для ссылок ig.me. Реферал рекламы Click-to-Direct использует тот же тип, но с source ADS.
Время, за которое приложение должно ответить после реферала в существующей переписке, что сбрасывает стандартное окно обмена сообщениями.
Как долго может действовать окно, открытое первым сообщением, отправленным после перехода по рекламе Click-to-Direct.
Где ссылки ig.me не поддерживаются по данным руководства Meta по ig.me.
Когда срабатывает messaging_referral?
Когда человек, у которого уже есть переписка с профессиональным аккаунтом, открывает ссылку ig.me с параметром ref. Instagram открывает существующий диалог, и Meta отправляет реферал самостоятельно, без сообщения. Куда придёт реферал, зависит от переписки и от действий человека:
Как выглядит уведомление о реферале?
Событие messaging, в котором объект referral находится рядом с sender, recipient и timestamp, без сообщения и postback. Руководство Meta по ig.me приводит значения реферала внутри той же структуры, что и другие события Instagram messaging:
{
"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.
"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.
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.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на