EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Webhook de mensagens do Instagram: payload da DM, ecos e campos

O campo messages do webhook do Instagram entrega as DMs de uma conta profissional assim que chegam: texto, anexos, compartilhamentos, respostas a Stories e menções, respostas inline e exclusões. Cada evento fica em um array messaging com o ID do remetente com escopo do Instagram, o destinatário, um timestamp e um objeto message, e as mensagens enviadas pela própria conta voltam pelo mesmo campo com is_echo definido como true.

O easyCoexistence inscreve cada conta do Instagram conectada em messages e encaminha suas DMs, incluindo os ecos, ao seu endpoint HTTPS assim que chegam, assinadas com o segredo daquela conta; o encaminhamento não mantém cópia, e as DMs não são armazenadas por padrão.

is_echo

Definido como true em um evento de mensagem enviada pela própria conta.

24 hours

Janela de mensagens padrão para a maioria das ações do usuário, durante a qual o app pode responder à pessoa.

ig_post

Tipo de anexo para um post compartilhado; o tipo antigo de compartilhamento teve suporte apenas até 1º de fevereiro de 2026.

story_mention

Tipo de anexo do evento de DM que a Meta envia quando alguém menciona a conta em um Story.

2534041

Subcódigo de erro, sob o código 200, quando o dono da conta desativou o acesso às mensagens diretas do Instagram.

Quando o campo messages é disparado?

Quando uma pessoa envia uma DM para a conta profissional e quando a conta envia uma. Os exemplos e referências da Meta listam estes casos, cada um um evento de mensagem com um objeto message:

  • Texto, e mídia como anexos: imagens, vídeo, áudio e arquivos.
  • Um post ou Reel compartilhado, como anexo ig_post, ig_reel ou reel.
  • Uma resposta ao Story da conta, com reply_to.story, e um Story que menciona a conta, como anexo story_mention.
  • Uma resposta em linha a uma mensagem anterior, com reply_to.mid, e uma resposta rápida, com quick_reply.payload.
  • Uma mensagem apagada pela pessoa (is_deleted), mídia não suportada (is_unsupported) e uma mensagem de alguém que clicou em um anúncio Click-to-Direct (referral).
  • Uma mensagem enviada pela conta, que volta com is_echo definido como true.

Como é uma notificação de mensagem?

Um POST cujo JSON tem object definido como instagram. Diferente de um comentário, a mensagem fica em um array messaging dentro da entrada da conta, e cada elemento traz sender, recipient, timestamp e message. Uma resposta ao Story da conta fica assim:

A messages notification, 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>",
            "text": "<MESSAGE_TEXT>",
            "reply_to": {
              "story": {
                "url": "<CDN_URL_FOR_THE_STORY>",
                "id": "<STORY_ID>"
              }
            }
          }
        }
      ]
    }
  ]
}

O que significa cada campo?

Os campos que a Meta documenta para um evento de mensagem no Instagram Login, de fora para dentro:

  • entry[].id: o ID da conta profissional. entry[].time: quando a Meta enviou a notificação; os exemplos de mensagens da Meta a trazem em milissegundos.
  • sender.id e recipient.id: em uma DM recebida, o ID com escopo do Instagram da pessoa e o ID da conta; em um eco, os mesmos dois na ordem inversa.
  • timestamp: quando a mensagem foi enviada, em milissegundos nos exemplos da Meta. Ordene as mensagens por ele, não pela ordem de chegada.
  • message.mid: o ID da mensagem, para deduplicar, reagir e responder a essa mensagem com reply_to.mid.
  • message.text: incluído quando a mensagem contém texto.
  • message.attachments[]: cada um com type e payload, geralmente uma url. O payload ig_post de um post compartilhado acrescenta ig_post_media_id e title, sua legenda.
  • message.reply_to: mid para uma resposta em linha, ou story com a url e o id do Story para uma resposta a Story.
  • message.quick_reply.payload e message.referral: a resposta rápida escolhida, e o ref, ad_id, source, type e ads_context_data do anúncio Click-to-Direct.
  • message.is_deleted, is_echo, is_self e is_unsupported: incluídos somente quando verdadeiros.
  • message.admin_text e handoff_reason: em apps elegíveis, um aviso de que um aplicativo da Meta, como o Meta Business Agent, transferiu a conversa; ele pode chegar sem mid nem text.

Como funcionam os ecos?

Quando a conta envia uma mensagem, a Meta também envia um evento de mensagem para ela, com is_echo definido como true. Então sender.id é a conta e recipient.id é o ID com escopo do Instagram da pessoa, e uma mensagem de teste que a conta envia para si mesma também traz is_self. Os ecos registram o que a conta disse, o que um log de conversa precisa, mas um handler que decide se responde deve ignorá-los. A Meta não envia eco quando a conta reage a uma mensagem ou remove uma reação.

An echo of a message the account sent
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448061203,
      "messaging": [
        {
          "sender": { "id": "<IG_ID>" },
          "recipient": { "id": "<IGSID>" },
          "timestamp": 1793448060950,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<REPLY_TEXT>",
            "is_echo": true
          }
        }
      ]
    }
  ]
}

Para qual ID você responde?

sender.id, o ID com escopo do Instagram da pessoa. A Meta o cria quando alguém envia uma mensagem para a conta ou comenta em sua mídia, e ele é específico para essa pessoa e essa conta. POST /<IG_ID>/messages com recipient.id definido como ele envia a resposta. O evento não traz nome nem username; GET /<IGSID> com campos como name e username os retorna, porque quem já enviou uma mensagem à conta deu o consentimento que essa consulta exige.

Como uma mensagem abre a janela de 24 horas?

Um app só pode enviar mensagens a uma pessoa depois que ela enviou uma mensagem à conta, e somente dentro da janela de mensagens padrão que a ação dela abre. Para a maioria das ações, ela dura 24 horas, e até 7 dias a partir de uma primeira mensagem enviada após clicar em um anúncio Click-to-Direct. Uma nova mensagem da pessoa abre uma nova janela, então o timestamp mais recente é o que deve ser acompanhado; um eco é mensagem da própria conta e não estende nada. Respostas escritas por um humano podem usar a janela separada de 7 dias do Human Agent da Meta, marcada como human_agent.

O que um evento de mensagem não traz?

Algumas coisas que um handler pode procurar estão ausentes, segundo as referências de mensagens da Meta:

  • O nome ou username da pessoa: apenas o ID com escopo do Instagram, que GET /<IGSID> resolve.
  • Mídia de visualização única: chega como anexo efêmero, sem URL.
  • A imagem exata do carrossel: uma reação a uma imagem de um post em carrossel, ou um encaminhamento dela, informa a primeira imagem.
  • Reações, edições e confirmações de leitura, que chegam em campos próprios.
  • Marca de leitura: uma mensagem entregue por webhook continua não lida na caixa do Instagram até que uma resposta seja enviada.

Quais outros campos de mensagem a Meta lista?

A lista de campos e exemplos da Meta para o Instagram Login cita estes além de messages, cada um um evento de mensagem próprio. O easyCoexistence assina cada conta apenas para messages, comments e mentions, então nenhum deles faz parte do que ele encaminha:

  • message_reactions: uma pessoa reage a uma mensagem ou remove a reação, com reaction.mid, action definido como react ou unreact, e a reação e o emoji.
  • message_edit: uma pessoa edita uma mensagem, com message_edit.mid, o novo texto e num_edit.
  • messaging_postbacks: uma pessoa toca em um icebreaker ou em um botão de template, com postback.mid, title e payload.
  • messaging_referral: uma pessoa que já está em uma conversa abre um link ig.me com o parâmetro ref.
  • messaging_seen: uma pessoa lê uma mensagem, com read.mid.
  • messaging_optins, messaging_handover e standby: os dois últimos para apps que compartilham uma conversa pelo protocolo de handover da Meta.

O que a conta precisa ativar?

Permitir acesso às mensagens. A Meta exige que uma conta profissional ative isso antes que as mensagens possam ser gerenciadas pela API, no app do Instagram em Configurações, Mensagens e respostas de Stories, Controles de mensagens, Ferramentas conectadas. Enquanto estiver desativado, os envios falham com o código 200, subcódigo 2534041. O app também precisa de instagram_business_basic e instagram_business_manage_messages, com Acesso Avançado para atender contas que ele não possui nem gerencia.

Como o easyCoexistence encaminha uma DM?

Como um comentário: cada entrada que a Meta entrega para a conta é enviada por POST ao seu endpoint HTTPS dentro de um envelope com platform, account_id, external_id e entry, assinado em X-EC-Signature com o segredo da conta, uma vez e sem manter cópia. Os ecos são encaminhados junto com o restante, então verifique is_echo antes de responder. Para responder, chame send_social_dm com o account_id e o sender.id do evento como recipient_id, dentro da janela de 24 horas. Automações que começam com uma DM rodam sobre os mesmos eventos.

A forwarded DM with an image
{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<IG_ID>",
  "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": "<URL_FOR_THE_MEDIA>" } }
          ]
        }
      }
    ]
  }
}

Erros comuns

  • Responder a ecos. Um evento com is_echo definido é a mensagem da própria conta, e uma resposta a ele coloca a conta em um loop com ela mesma.
  • Presumir que uma mensagem sempre tem texto. Anexos, compartilhamentos, menções em Stories e exclusões chegam sem campo text, então faça a lógica conforme o que o objeto message contém.
  • Ordenar mensagens pela ordem de chegada. A Meta pode entregar mensagens fora de ordem após uma falha, então ordene-as por timestamp.
  • Ler time e timestamp como segundos. Os exemplos de mensagens da Meta trazem ambos em milissegundos, e lidos como segundos viram datas muito no futuro.
Fazendo isso com o EasyCoexistence

send_social_dm responde dentro da janela de 24 horas, e as automações podem responder sozinhas com um texto fixo ou com IA. 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

Os timestamps dos webhooks de mensagens do Instagram estão em segundos ou milissegundos?

Em milissegundos, nos exemplos de mensagens da Meta, tanto para timestamp quanto para o horário da entrada. Lidos como segundos, viram datas muito no futuro.

Como obtenho o username do remetente a partir de uma DM do webhook do Instagram?

Chame GET /<IGSID> com campos como name e username. O evento traz apenas o ID com escopo do Instagram da pessoa.

Por que os webhooks de DM do Instagram não estão chegando?

Verifique se a conta ativou Permitir acesso às mensagens, se está assinada para messages por /subscribed_apps e se o app está Live com Acesso Avançado para contas que ele não possui.

O easyCoexistence encaminha reações em mensagens do Instagram?

Não. As reações chegam em message_reactions, e o easyCoexistence assina as contas para messages, comments e mentions.

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