EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Anexos de DM do Instagram no webhook de mensagens

O webhook de mensagens do Instagram traz a mídia das DMs em message.attachments: um array de objetos, cada um com um type e um payload que normalmente contém uma URL da CDN. A lista da Meta para o Instagram Login inclui image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story e o share legado, e a mídia de visualização única chega como um anexo efêmero sem URL.

O easyCoexistence inscreve cada conta do Instagram conectada em messages e encaminha as DMs com seus anexos para o seu endpoint HTTPS exatamente como a Meta as envia, assinadas com o segredo daquela conta e sem cópia armazenada, para que o seu agente ou código busque a mídia de que precisar.

ig_post

Tipo de anexo de um post compartilhado; seu payload acrescenta ig_post_media_id e title, a legenda do post, ao lado de url.

1 Feb 2026

Quando o antigo tipo de anexo share deixou de ser suportado para compartilhamentos de posts do Instagram.

ephemeral

Tipo de anexo de mídia que desaparece, de visualização única, que chega sem URL.

is_unsupported

Definido como true em um evento de mensagem quando a mensagem contém mídia não suportada.

First image

O que uma notificação informa quando alguém reage ou encaminha uma imagem de um post em carrossel.

Quais tipos de anexo um evento de DM pode trazer?

Os exemplos de Instagram Login da Meta listam estes valores para message.attachments[].type, cada um com um objeto payload. A maioria dos payloads traz uma url para a mídia na CDN da Meta, e a Meta documenta campos extras de payload apenas para ig_post, então leia o type antes do payload.

imageA photo. Meta's Instagram Login list also puts GIFs and stickers under this type.
videoA video, at payload.url.
audioAudio, at payload.url.
fileA file, at payload.url.
ig_postA shared post: url, ig_post_media_id and title, its caption.
ig_reel and reelA shared Reel; Meta lists both names, each with a url.
story_mentionA Story that mentions the account, at its CDN URL.
shareThe legacy post share, supported until 1 February 2026.
media, story, ig_storyAlso in Meta's list, with no payload described.
ephemeralView-once media, sent with no URL.

Como é uma DM com anexos?

Um evento de mensagem cujo objeto message traz attachments no lugar do texto, ou junto com ele. O exemplo da Meta envia duas mídias em uma mesma mensagem, cada uma com seu próprio type e payload.url, então o código precisa percorrer o array em vez de ler apenas o primeiro elemento:

A DM with two attachments, as Meta sends it
{
  "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 é um post compartilhado?

Um anexo ig_post. A partir de 3 de novembro de 2025, a Meta enviou compartilhamentos de posts com um anexo share e um anexo ig_post; share foi suportado para posts até 1º de fevereiro de 2026, e a Meta diz que novas integrações devem suportar ig_post. Seu payload acrescenta o ID da mídia do post e sua legenda como title:

The attachment of a shared post
"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, do array para baixo:

  • message.attachments[]: um objeto por item de mídia; o exemplo da Meta traz dois em uma mesma mensagem.
  • type: o que o item é, a partir da lista acima. Faça a ramificação pelo type antes de ler o payload.
  • payload.url: uma URL da CDN para a mídia. A visão geral da Meta chama essas URLs de que respeitam a privacidade: elas não retornam nada quando o conteúdo é excluído ou expira.
  • payload.ig_post_media_id e payload.title: apenas em ig_post, o ID da mídia do post compartilhado e sua legenda.
  • message.text: presente apenas quando a mensagem também contém texto.
  • message.is_unsupported: true quando a mensagem contém mídia que o webhook não suporta.

Por quanto tempo as URLs de anexo funcionam?

A Meta as vincula ao conteúdo. A visão geral diz que as URLs da CDN do Instagram respeitam a privacidade e deixam de retornar a mídia quando o conteúdo é excluído ou expira, e o guia de menções em Story diz que a URL de um Story deixa de ser renderizada quando o Story expira ou é excluído. Um app que precisa de um arquivo deve buscá-lo ao chegar o evento, dentro das regras da Meta: a mídia de Story, por exemplo, não pode ser armazenada nem em cache.

Quais mídias o webhook deixa de fora?

O guia de mensagens do Instagram da Meta cita estas lacunas, que o código deve esperar em vez de tratar como erros:

  • Mídia que desaparece, de visualização única ou com reprodução permitida: um anexo do tipo ephemeral, sem URL.
  • Mídia não suportada: a mensagem chega com is_unsupported definido como true.
  • GIFs e figurinhas: esse guia diz que não disparam webhook, enquanto os exemplos de Instagram Login da Meta os listam em image.
  • A imagem escolhida do carrossel: uma reação a, ou um encaminhamento de, uma imagem em um post em carrossel informa a primeira imagem.
  • Compartilhamentos em geral: os guias de mensagens da Meta ainda dizem que apenas a URL da mídia compartilhada é incluída, embora ig_post agora acrescente o ID da mídia e a legenda.

Como o easyCoexistence encaminha os anexos?

Inalterado, dentro do entry: uma DM com mídia chega ao seu endpoint com o array attachments da Meta como a Meta o enviou, em um envelope com platform, account_id, external_id e entry, assinado com X-EC-Signature. Os anexos não são baixados, e os eventos não são armazenados por padrão: uma conta com automação ativada mantém o texto de uma DM, não a mídia, por 7 dias. Busque a mídia de que precisar em payload.url ao chegar o evento, e não guarde a mídia de Story.

Erros comuns

  • Ler apenas o primeiro anexo. message.attachments é um array, e o exemplo da Meta traz dois itens em uma mesma mensagem, então percorra-o.
  • Continuar buscando o type share em posts compartilhados. A Meta o suportou para posts até 1º de fevereiro de 2026; leia ig_post, com o ID da mídia e a legenda em seu payload.
  • Salvar payload.url para buscar depois. Ela deixa de retornar mídia quando o conteúdo é excluído ou expira, então baixe o que precisar ao chegar, exceto a mídia de Story.
  • Ler payload.url sem verificar o type. A mídia de visualização única chega como ephemeral sem URL, e a mídia não suportada define is_unsupported.
Fazendo isso com o EasyCoexistence

send_social_dm responde dentro da janela de atendimento de 24 horas. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com 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

Posso armazenar mídia de um anexo de DM do Instagram?

Baixe o que precisar quando o evento chegar, pois payload.url deixa de retornar mídia quando o conteúdo é excluído ou expira. A mídia de Story é a exceção: as regras da Meta dizem que ela não pode ser armazenada nem em cache.

Por que um webhook de DM do Instagram não tem URL de mídia?

Geralmente porque a mídia é de visualização única, que chega como anexo ephemeral sem URL, ou não é suportada, o que define is_unsupported como true.

GIFs e figurinhas do Instagram disparam o webhook de mensagens?

A documentação da Meta diverge: os exemplos de Instagram Login listam GIFs e figurinhas em image, enquanto o guia de mensagens do Instagram diz que eles não disparam webhook. Teste com uma conta real.

Um mesmo evento de DM do Instagram pode trazer vários anexos?

Sim. message.attachments é um array, e o exemplo da Meta mostra dois itens de mídia em uma única mensagem.

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