Anexos de DM do Instagram no webhook de mensagens
O webhook de mensagens do Instagram transporta os conteúdos multimédia das DM em message.attachments: uma lista de objetos, cada um com um type e um payload que normalmente contém um URL da CDN. A lista da Meta para o Instagram Login indica image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story e o tipo share legado, e os conteúdos de visualização única chegam como anexo efémero sem URL.
A easyCoexistence subscreve cada conta do Instagram ligada a mensagens e reencaminha as DM com os respetivos anexos para o seu endpoint HTTPS tal como a Meta os envia, assinados com o segredo dessa conta e sem cópia guardada, para que o seu agente ou código obtenha o conteúdo de que precisa.
Tipo de anexo de uma publicação partilhada; o seu payload acrescenta ig_post_media_id e title, a legenda da publicação, ao lado de url.
Quando o antigo tipo de anexo share deixou de ser suportado para partilhas de publicações do Instagram.
Tipo de anexo de conteúdo efémero de visualização única, que chega sem URL.
Definido como true num evento de mensagem quando a mensagem contém conteúdo multimédia não suportado.
O que uma notificação indica quando alguém reage ou reencaminha uma imagem de uma publicação em carrossel.
Que tipos de anexo pode trazer um evento de DM?
Os valores da Meta para o Instagram Login listam estes valores de message.attachments[].type, cada um com um objeto payload. A maioria dos payloads contém um url para o conteúdo na CDN da Meta, e a Meta documenta campos extra de payload apenas para ig_post; leia, por isso, o type antes do payload.
Como é uma DM com anexos?
Um evento de mensagens cujo objeto message contém attachments em vez de texto, ou junto com ele. O exemplo da Meta envia dois conteúdos numa só mensagem, cada um com o seu type e payload.url, por isso o handler tem de percorrer a lista em vez de ler apenas o primeiro elemento:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<CDN_URL>" } },
{ "type": "video", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
]
}Como é uma publicação partilhada?
Um anexo ig_post. A partir de 3 de novembro de 2025 a Meta enviou partilhas de publicações com um anexo share e um anexo ig_post; share foi suportado para publicações até 1 de fevereiro de 2026, e a Meta indica que as novas integrações têm de suportar ig_post. O payload acrescenta o ID do conteúdo multimédia da publicação e a sua legenda como title:
"attachments": [
{
"type": "ig_post",
"payload": {
"ig_post_media_id": "<MEDIA_ID>",
"title": "<POST_CAPTION>",
"url": "<CDN_URL>"
}
}
]O que significa cada campo?
Os campos de anexo que a Meta documenta para um evento de DM, desde a lista até ao nível mais baixo:
- message.attachments[]: um objeto por conteúdo; o exemplo da Meta traz dois numa só mensagem.
- type: o que o item é, da lista acima. Verifique-o antes de ler o payload.
- payload.url: um URL da CDN para o conteúdo. A visão geral da Meta descreve estes URL como respeitadores da privacidade: deixam de devolver conteúdo assim que este é eliminado ou expira.
- payload.
ig_post_media_ide payload.title: só emig_post, o ID do conteúdo da publicação partilhada e a sua legenda. - message.text: presente apenas quando a mensagem também contém texto.
- message.
is_unsupported: true quando a mensagem contém conteúdo que o webhook não suporta.
Quanto tempo funcionam os URL dos anexos?
A Meta liga-os ao conteúdo. A visão geral indica que os URL da CDN do Instagram respeitam a privacidade e deixam de devolver o conteúdo depois de este ser eliminado ou expirar, e o guia de menções em Stories diz que o URL de um Story deixa de ser apresentado quando o Story expira ou é eliminado. Uma aplicação que precise de um ficheiro deve obtê-lo quando o evento chega, dentro das regras da Meta: o conteúdo de Stories, por exemplo, não pode ser armazenado nem colocado em cache.
Que conteúdos o webhook deixa de fora?
O guia de mensagens do Instagram da Meta indica estas lacunas, que um handler deve esperar em vez de tratar como erros:
- Conteúdo efémero, de visualização única ou com repetição permitida: um anexo do tipo ephemeral, sem URL.
- Conteúdo não suportado: a mensagem chega com
is_unsupporteddefinido como true. - GIF e autocolantes: esse guia indica que não disparam webhook, enquanto os exemplos do Instagram Login da Meta os listam em image.
- A imagem escolhida de um carrossel: uma reação a, ou um reencaminhamento de, uma imagem de uma publicação em carrossel indica a primeira imagem.
- Partilhas em geral: os guias de mensagens da Meta ainda indicam que só o URL do conteúdo partilhado é incluído, embora
ig_postpasse agora a acrescentar o ID e a legenda.
Como o easyCoexistence reencaminha os anexos?
Sem alterações, dentro de entry: uma DM com conteúdo multimédia chega ao seu endpoint com o array attachments da Meta tal como a Meta o enviou, num envelope com platform, account_id, external_id e entry, assinado com X-EC-Signature. Os anexos não são transferidos, e os eventos não são guardados por defeito: uma conta com uma automatização ativa guarda o texto de uma DM, e não o seu conteúdo multimédia, durante 7 dias. Obtenha o conteúdo de que precisa a partir de payload.url quando o evento chegar, e não guarde o conteúdo de Stories.
Erros comuns
- Ler apenas o primeiro anexo. message.attachments é uma lista, e o exemplo da Meta traz dois itens numa só mensagem, por isso percorra-a.
- Continuar a procurar o tipo share nas publicações partilhadas. A Meta suportou-o para publicações até 1 de fevereiro de 2026; leia ig_post, com o ID do conteúdo e a legenda no payload.
- Guardar payload.url para obter mais tarde. Deixa de devolver conteúdo quando este é eliminado ou expira, por isso transfira o que precisa ao chegar, à exceção do conteúdo de Stories.
- Ler payload.url sem verificar o tipo. O conteúdo de visualização única chega como ephemeral sem URL, e o conteúdo não suportado define is_unsupported em vez disso.
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 grátis.
Perguntas frequentes
Posso guardar conteúdo de um anexo de DM do Instagram?
Transfira o que precisar quando o evento chegar, já que payload.url deixa de devolver conteúdo quando este é eliminado ou expira. Os conteúdos de Stories são a exceção: as regras da Meta indicam que não podem ser armazenados nem colocados em cache.
Porque é que um webhook de DM do Instagram não tem URL de conteúdo?
Normalmente porque o conteúdo é de visualização única, que chega como anexo efémero sem URL, ou não é suportado, o que define is_unsupported como true.
Os GIF e autocolantes do Instagram disparam o webhook de mensagens?
A documentação da Meta não é coerente: os exemplos do Instagram Login listam GIF e autocolantes em image, enquanto o guia de mensagens do Instagram indica que não disparam webhook. Teste com uma conta real.
Pode um único evento de DM do Instagram trazer vários anexos?
Sim. message.attachments é uma lista, e o exemplo da Meta mostra dois conteúdos numa só mensagem.
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