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.
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.
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.
Tempo que a aplicação tem para responder após uma referência numa conversa existente, o que repõe a janela padrão.
Até quanto tempo pode durar a janela a partir de uma primeira mensagem enviada após clicar num anúncio Click-to-Direct.
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:
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:
{
"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.
"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.
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