Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Webhook messaging_referral do Instagram: links ig.me e referências de anúncios

O campo messaging_referral do webhook do Instagram notifica uma aplicação quando uma pessoa que já tem uma conversa com uma conta profissional abre um link ig.me com o parâmetro ref. O evento contém um objeto referral de nível superior: ref, o valor do parâmetro; source, SHORTLINKS; e type, OPEN_THREAD. Um ref numa conversa nova chega, em vez disso, dentro do evento messages ou messaging_postbacks.

O easyCoexistence subscreve cada conta do Instagram ligada a comentários, mensagens e menções, por isso uma referência na primeira mensagem de uma conversa nova e a referência de um anúncio Click-to-Direct chegam ao seu endpoint HTTPS dentro da DM reencaminhada, assinada com o segredo dessa conta.

2,083

O máximo de caracteres que um parâmetro ref de ig.me pode ter, usando apenas letras, algarismos, hífenes, sublinhados e sinais de igual.

OPEN_THREAD

Tipo de referência para links ig.me; a referência de um anúncio Click-to-Direct também o usa, com source ADS.

24 hours

Tempo que a aplicação tem para responder após uma referência numa conversa existente, o que repõe a janela padrão.

7 days

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

Instagram Web

Onde os links ig.me não são suportados, segundo o guia ig.me da Meta.

Quando é que o messaging_referral dispara?

Quando uma pessoa que já tem uma conversa com a conta profissional abre um link ig.me que contém um parâmetro ref. O Instagram abre a conversa existente e a Meta envia a referência por conta própria, sem qualquer mensagem. Onde chega uma referência 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 referência?

Um evento de mensagens cujo objeto referral está ao lado de sender, recipient e timestamp, sem mensagem nem postback à sua volta. O guia ig.me da Meta indica os valores da referência, dentro do mesmo envelope dos restantes 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 uma referência ig.me, do exterior para o interior:

  • sender.id: o ID de âmbito 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, tal como o link o continha.
  • referral.source: SHORTLINKS nos exemplos ig.me da Meta. Uma tabela do seu guia de Mensagens do Instagram escreve SHORTLINK, e a página de exemplos mostra um marcador de posição.
  • referral.type: OPEN_THREAD, que a Meta usa nas referências ig.me.
  • timestamp: o momento em que o evento foi disparado, em milissegundos nos exemplos da Meta.

Como se cria um link ig.me com um ref?

Como https://ig.me/<USERNAME>?ref=<VALUE>, em que USERNAME é o nome de utilizador da conta profissional, segundo o guia Instagram Login da Meta; o seu guia de Mensagens do Instagram escreve https://ig.me/m/<USERNAME>. O ref pode ter até 2,083 caracteres de letras, algarismos, hífenes, sublinhados e sinais de igual. A Meta sugere refs para monitorizar canais, associar uma pessoa a uma sessão noutra aplicação ou encaminhá-la para conteúdos específicos, e recomenda ice breakers, cada um com o seu próprio ref, para novas conversas.

Onde chegam as referências de anúncios?

Nas mensagens. Uma pessoa que clica num anúncio que abre o Instagram Direct e envia uma mensagem gera um evento messages cujo message.referral contém o ref do anúncio, caso tenha sido 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 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>"
    }
  }
}

Uma referência abre a janela de mensagens?

Sim, numa conversa existente: o guia ig.me da Meta diz que a referência repõe a janela padrão de mensagens de 24 horas, pelo que a aplicação pode responder dentro de 24 horas após o evento. Uma primeira mensagem enviada após clicar num anúncio Click-to-Direct pode abrir uma janela de até 7 dias a contar dessa mensagem. Responda com POST /<IG_ID>/messages e recipient.id definido como o sender.id do evento.

O easyCoexistence reencaminha referências?

As que chegam nas mensagens. Cada conta do Instagram ligada está subscrita a comentários, mensagens e menções, por isso uma referência na primeira mensagem de uma conversa nova e a referência de um anúncio Click-to-Direct chegam ao seu endpoint dentro da DM reencaminhada, como message.referral. messaging_referral, para conversas existentes, e messaging_postbacks, para toques em ice breakers, são campos distintos que a Meta entrega a uma aplicação subscrita a eles.

Erros comuns

  • Esperar messaging_referral numa conversa nova. Aí a referência chega em messages ou messaging_postbacks, conforme a pessoa tenha escrito ou tocado num ice breaker.
  • Pôr outros caracteres em ref. A Meta aceita letras, algarismos, hífenes, sublinhados e sinais de igual, até 2,083 caracteres.
  • Comparar source com uma única cadeia exata. Os exemplos da Meta mostram SHORTLINKS para ig.me e ADS para anúncios, mas uma das tabelas escreve SHORTLINK, por isso distinga pela posição da referência e pelo ref.
  • Testar links no Instagram Web. A Meta não suporta links ig.me aí, por isso abra-os na aplicação do Instagram.
Fazer isto com a EasyCoexistence

send_social_dm responde dentro da janela de 24 horas. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

O que contém referral.source numa referência do Instagram?

SHORTLINKS nos exemplos 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. Distinga pela posição da referência e pelo ref, em vez de uma única cadeia exata.

Qual é o tamanho máximo de um parâmetro ref de ig.me?

Até 2,083 caracteres, usando apenas letras, algarismos, hífenes, sublinhados e sinais de igual.

Onde chega um ref de ig.me numa nova conversa do Instagram?

Em messages quando a pessoa escreve uma primeira mensagem, ou em messaging_postbacks quando toca num ice breaker. messaging_referral cobre apenas conversas existentes.

Os links ig.me funcionam no Instagram Web?

Não. O guia ig.me da Meta diz que não são suportados no Instagram Web.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em