Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Webhook de mensagens do Instagram: o payload de DM, os echos e os campos

O campo messages do webhook do Instagram entrega as DM de uma conta profissional à medida que chegam: texto, anexos, partilhas, respostas a Stories e menções, respostas em linha e eliminações. Cada evento fica num array messaging com o ID com âmbito do Instagram do remetente, o destinatário, um timestamp e um objeto message, e as mensagens que a própria conta envia voltam no mesmo campo com is_echo a true.

A easyCoexistence subscreve cada conta do Instagram ligada a messages e encaminha as suas DM, incluindo os echos, para o seu endpoint HTTPS à medida que chegam, assinadas com o segredo dessa conta; o reencaminhamento não guarda cópia, e as DM não são guardadas por defeito.

is_echo

Definido como true num evento de mensagem para uma mensagem enviada pela própria conta.

24 hours

Janela de mensagens predefinida para a maioria das ações dos utilizadores, durante a qual a aplicação pode responder à pessoa.

ig_post

Tipo de anexo para uma publicação partilhada; o antigo tipo de partilha só foi suportado 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 na sua Story.

2534041

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

Quando é acionado o campo messages?

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

  • Texto, e multimédia como anexos: imagens, vídeo, áudio e ficheiros.
  • Uma publicação ou Reel partilhado, como anexo ig_post, ig_reel ou reel.
  • Uma resposta a uma Story da conta, com reply_to.story, e uma 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 que a pessoa eliminou (is_deleted), multimédia não suportado (is_unsupported) e uma mensagem de alguém que clicou num anúncio Click-to-Direct (referral).
  • Uma mensagem que a conta enviou, que volta com is_echo a true.

Como é uma notificação de mensagens?

Um POST cujo JSON tem object com o valor instagram. Ao contrário de um comentário, uma mensagem fica num array messaging dentro da entrada da conta, e cada elemento inclui sender, recipient, timestamp e message. Uma resposta a uma Story da conta tem este aspeto:

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 com o 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 indicam-no em milissegundos.
  • sender.id e recipient.id: numa DM recebida, o ID da pessoa com âmbito do Instagram e o ID da conta; num echo, os mesmos dois ao contrário.
  • timestamp: quando a mensagem foi enviada, em milissegundos nos exemplos da Meta. Ordene as mensagens por este valor, e 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 um type e um payload, normalmente um url. O payload ig_post de uma publicação partilhada acrescenta ig_post_media_id e title, a sua legenda.
  • message.reply_to: mid numa resposta em linha, ou story com o url e o id da Story numa resposta a uma 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 apenas quando são true.
  • message.admin_text e handoff_reason: em aplicações elegíveis, um aviso de que uma aplicação da Meta, como o Meta Business Agent, transferiu a conversa; pode chegar sem mid nem text.

Como funcionam os echos?

Quando a conta envia uma mensagem, a Meta envia também um evento de mensagem para ela, com is_echo a true. Nesse caso, sender.id é a conta e recipient.id é o ID da pessoa com âmbito do Instagram, e uma mensagem de teste que a conta envia para si própria traz também is_self. Os echos registam o que a conta disse, algo de que um registo de conversas precisa, mas o código que decide se deve responder tem de os ignorar. A Meta não envia nenhum echo 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
          }
        }
      ]
    }
  ]
}

A que ID se responde?

sender.id, o ID da pessoa com âmbito do Instagram. A Meta cria-o quando alguém envia uma mensagem à conta ou comenta as suas publicações, e é específico dessa pessoa e dessa conta. POST /<IG_ID>/messages com recipient.id definido como esse valor envia a resposta. O evento não traz nome nem nome de utilizador; GET /<IGSID> com campos como name e username devolve-os, porque uma pessoa que enviou uma mensagem à conta deu o consentimento de que essa consulta precisa.

Como é que uma mensagem abre a janela de 24 horas?

Uma aplicação só pode enviar mensagens a uma pessoa depois de ela ter enviado uma mensagem à conta, e apenas dentro da janela de mensagens predefinida que a ação dessa pessoa abre. Para a maioria das ações, dura 24 horas, e até 7 dias a partir de uma primeira mensagem enviada após clicar num anúncio Click-to-Direct. Uma nova mensagem da pessoa abre uma nova janela, por isso é o timestamp mais recente que deve acompanhar; um echo é uma mensagem da própria conta e não prolonga nada. As respostas escritas por uma pessoa podem usar a janela separada de 7 dias da Meta, Human Agent, marcada com human_agent.

O que um evento de mensagens não traz?

Algumas coisas que o código poderia procurar estão em falta, segundo as referências de mensagens da Meta:

  • O nome ou nome de utilizador da pessoa: apenas o ID com âmbito do Instagram, que o GET /<IGSID> resolve.
  • Multimédia de visualização única: chega como anexo efémero, sem URL.
  • A imagem exata de um carrossel: uma reação a, ou um reencaminhamento de, uma imagem de uma publicação em carrossel indica a primeira imagem.
  • Reações, edições e confirmações de leitura, que chegam em campos próprios.
  • Uma marca de leitura: uma mensagem entregue por webhook fica por ler na caixa de entrada do Instagram até ser enviada uma resposta.

Que outros campos de mensagens lista a Meta?

A lista de campos e os exemplos da Meta para o Instagram Login indicam, além de messages, estes outros, cada um um evento de mensagem próprio. A easyCoexistence subscreve cada conta apenas a messages, comments e mentions, por isso nenhum deles faz parte do que encaminha:

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

O que a conta tem de ativar?

Permitir acesso a mensagens. A Meta exige que uma conta profissional o ative antes de as suas mensagens poderem ser geridas pela API, na aplicação do Instagram, em Definições, Mensagens e respostas de Stories, Controlos de mensagens, Ferramentas ligadas. Enquanto estiver desativado, os envios falham com código 200, subcódigo 2534041. A aplicação precisa também de instagram_business_basic e instagram_business_manage_messages, com Acesso Avançado para servir contas que não possui nem gere.

Como é que a easyCoexistence encaminha uma DM?

Tal como um comentário: cada entrada que a Meta entrega para a conta é enviada por POST para o seu endpoint HTTPS dentro de um envelope com platform, account_id, external_id e entry, assinada em X-EC-Signature com o segredo da conta, uma única vez e sem guardar cópia. Os echos são encaminhados com o resto, por isso 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. As automações que começam numa DM correm 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 echos. Um evento com is_echo é a mensagem da própria conta, e responder-lhe envia a conta para um ciclo consigo mesma.
  • Assumir que uma mensagem tem sempre texto. Anexos, partilhas, menções em Stories e eliminações chegam sem campo text, por isso trate cada caso conforme o que o objeto message contém.
  • Ordenar as mensagens pela ordem de chegada. A Meta pode entregar mensagens fora de ordem depois de uma falha, por isso ordene-as por timestamp.
  • Interpretar time e timestamp como segundos. Os exemplos de mensagens da Meta dão ambos em milissegundos, e lidos como segundos transformam-se em datas muito no futuro.
Fazer isto com a 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 ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

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 no timestamp como na hora de entrada. Lidos como segundos, transformam-se em datas muito no futuro.

Como obtenho o nome de utilizador do remetente a partir de uma DM do Instagram?

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

Porque é que os webhooks de DM do Instagram não chegam?

Verifique se a conta ativou Permitir acesso a mensagens, se está subscrita a messages através de /subscribed_apps, e se a aplicação está Live com Acesso Avançado para contas que não possui.

A easyCoexistence encaminha as reações às mensagens do Instagram?

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

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