EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

2,083

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.

OPEN_THREAD

Tipo de referral para links ig.me; o referral de um anúncio Click-to-Direct também usa esse tipo, com source ADS.

24 hours

Tempo que o aplicativo tem para responder após um referral em uma conversa existente, o que reinicia a janela padrão.

7 days

Por quanto tempo a janela pode durar a partir de uma primeira mensagem enviada após clicar em um anúncio Click-to-Direct.

Instagram Web

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:

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.

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:

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"
          }
        }
      ]
    }
  ]
}

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.

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>"
    }
  }
}

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.
Fazendo isso com o EasyCoexistence

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