Webhook messaging_referral do Instagram: links ig.me e referrals de anúncios
O campo messaging_referral do webhook do Instagram notifica um aplicativo quando uma pessoa que já tem uma conversa com uma conta profissional abre um link ig.me com o parâmetro ref. O evento traz um objeto referral no nível superior: ref, o valor do parâmetro; source, SHORTLINKS; e type, OPEN_THREAD. Um ref em uma conversa nova chega dentro do evento messages ou messaging_postbacks.
O easyCoexistence inscreve cada conta do Instagram conectada em comentários, mensagens e menções, então um ref na primeira mensagem de uma conversa nova e o referral de um anúncio Click-to-Direct chegam ao seu endpoint HTTPS dentro da DM encaminhada, assinada com o segredo daquela conta.
Número máximo de caracteres de um parâmetro ref de ig.me, usando apenas letras, dígitos, hífens, sublinhados e sinais de igual.
Tipo de referral para links ig.me; o referral de um anúncio Click-to-Direct também usa esse tipo, com source ADS.
Tempo que o aplicativo tem para responder após um referral em uma conversa existente, o que reinicia a janela padrão.
Por quanto tempo a janela pode durar a partir de uma primeira mensagem enviada após clicar em um anúncio Click-to-Direct.
Onde os links ig.me não são suportados, segundo o guia de ig.me da Meta.
Quando o messaging_referral é disparado?
Quando uma pessoa que já tem uma conversa com a conta profissional abre um link ig.me que carrega um parâmetro ref. O Instagram abre a conversa existente e a Meta envia o referral por conta própria, sem mensagem. Onde um ref chega depende da conversa e do que a pessoa faz:
Como é uma notificação de referral?
Um evento de mensagem cujo objeto referral fica ao lado de sender, recipient e timestamp, sem message nem postback ao redor. O guia de ig.me da Meta traz os valores do referral, dentro do mesmo envelope dos outros eventos de mensagens do Instagram:
{
"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"
}
}
]
}
]
}O que significa cada campo?
Os campos que a Meta documenta para um referral de ig.me, de fora para dentro:
- sender.id: o ID com escopo do Instagram da pessoa que abriu o link. recipient.id e entry[].id: a conta profissional.
- referral.ref: o valor do parâmetro ref do link, exatamente como o link o carregava.
- referral.source: SHORTLINKS nos exemplos de ig.me da Meta. Uma tabela do guia de Mensagens do Instagram escreve SHORTLINK, e a página de exemplos mostra um placeholder.
- referral.type:
OPEN_THREAD, que a Meta usa para referrals de ig.me. - timestamp: quando o evento foi disparado, em milissegundos nos exemplos da Meta.
Como montar um link ig.me com ref?
Como https://ig.me/<USERNAME>?ref=<VALUE>, em que USERNAME é o identificador da conta profissional, segundo o guia de Instagram Login da Meta; o guia de Mensagens do Instagram escreve https://ig.me/m/<USERNAME>. O ref pode ter até 2,083 caracteres entre letras, dígitos, hífens, sublinhados e sinais de igual. A Meta sugere refs para rastrear canais, vincular uma pessoa a uma sessão em outro app ou direcioná-la a conteúdos específicos, e recomenda ice breakers, cada um com seu próprio ref, para novas conversas.
Onde chegam os referrals de anúncios?
Em messages. Uma pessoa que clica em um anúncio que abre o Instagram Direct e envia uma mensagem gera um evento messages cujo message.referral traz o ref do anúncio, se houver um definido, ad_id, source ADS, type OPEN_THREAD e ads_context_data com o título do anúncio e o photo_url ou video_url clicado. As páginas do Instagram da Meta documentam o messaging_referral apenas para links 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>"
}
}
}Um referral abre a janela de mensagens?
Sim, em uma conversa existente: o guia de ig.me da Meta diz que o referral reinicia a janela padrão de mensagens de 24 horas, então o aplicativo pode responder em até 24 horas do evento. Uma primeira mensagem enviada após clicar em um anúncio Click-to-Direct pode abrir uma janela de até 7 dias a partir dessa mensagem. Responda com POST /<IG_ID>/messages e recipient.id definido como o sender.id do evento.
O easyCoexistence encaminha referrals?
Os que viajam em messages. Cada conta conectada é inscrita em comentários, mensagens e menções, então um ref na primeira mensagem de uma conversa nova e o referral de um anúncio Click-to-Direct chegam ao seu endpoint dentro da DM encaminhada, como message.referral. messaging_referral, para conversas existentes, e messaging_postbacks, para toques em ice breakers, são campos separados que a Meta entrega a um aplicativo inscrito neles.
Erros comuns
- Esperar o messaging_referral em uma conversa nova. Lá o ref chega em messages ou messaging_postbacks, dependendo de a pessoa ter digitado ou tocado em um ice breaker.
- Colocar outros caracteres no ref. A Meta aceita letras, dígitos, hífens, sublinhados e sinais de igual, até 2,083 caracteres.
- Comparar source com uma única string exata. Os exemplos da Meta mostram SHORTLINKS para ig.me e ADS para anúncios, mas uma tabela traz SHORTLINK; então decida pelo local onde o referral aparece e pelo ref.
- Testar links no Instagram Web. A Meta não suporta links ig.me ali, então abra-os no aplicativo do Instagram.
send_social_dm responde dentro da janela de 24 horas. De US$ 9 a US$ 0.75 por conexão por mês, com a queda conforme você adiciona conexões, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
O que o referral.source contém em um referral do Instagram?
SHORTLINKS nos exemplos de ig.me da Meta e ADS para um anúncio Click-to-Direct, embora uma tabela do guia de Mensagens do Instagram da Meta escreva SHORTLINK. Decida pelo local onde o referral aparece e pelo ref, em vez de uma única string exata.
Qual o tamanho máximo do parâmetro ref de um link ig.me?
Até 2,083 caracteres, usando apenas letras, dígitos, hífens, sublinhados e sinais de igual.
Onde o ref de ig.me chega em uma conversa nova do Instagram?
Em messages quando a pessoa digita uma primeira mensagem, ou em messaging_postbacks quando ela toca em um ice breaker. O messaging_referral cobre apenas conversas existentes.
Os links ig.me funcionam no Instagram Web?
Não. O guia de ig.me da Meta diz que eles não são suportados no Instagram Web.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em