Campos de webhook do Instagram: a lista completa
Para uma conta profissional com Instagram Login, a tabela de campos de webhook da Meta lista comments, live_comments, messages, message_echoes, message_reactions, messaging_postbacks, messaging_referral, messaging_seen, messaging_optins, messaging_handover e standby, com as menções entregues dentro de comments; os seus exemplos acrescentam message_edit. Cada um precisa de instagram_business_basic mais instagram_business_manage_comments ou, na maioria dos campos de mensagens, de instagram_business_manage_messages. story_insights não é oferecido com Instagram Login.
A easyCoexistence subscreve cada conta do Instagram ligada a comments, messages e mentions, e encaminha esses eventos para o seu endpoint HTTPS à medida que chegam, assinados com a chave secreta dessa conta.
Campos a que um novo produto Instagram no painel da aplicação na Meta começa subscrito, entre eles comments, messages e message_reactions.
Os campos são escolhidos para a aplicação, não por conta: uma conta recebe os campos que a aplicação escolheu.
Nível de acesso que o guia de configuração da Meta indica para os webhooks do Instagram Login, e que exige para as notificações de comments e live_comments.
Assinalado como indisponível com Instagram Login na tabela de campos da Meta, que o oferece com Facebook Login e Unified Login.
Quando a Meta introduziu o webhook message_edit para Business Login for Instagram e Facebook Login for Business.
Que campos de webhook oferece o Instagram Login?
Estes, da tabela de campos da Meta, com o que dispara cada um tirado dos seus exemplos e da referência de webhooks. Cada campo precisa também de instagram_business_basic, além da permissão indicada, e a Meta exige Advanced Access para as notificações de comments e live_comments.
Que campos não estão disponíveis com o Instagram Login?
Três linhas da tabela de campos da Meta não têm permissão para o Instagram Login, pelo que uma aplicação com Instagram Login não os recebe, e outro campo existe apenas fora dele:
story_insights: as métricas de uma Story quando expira, com Facebook Login ou Unified Login einstagram_manage_insights. A referência de media insights da Meta diz que o webhook de insights não é suportado com Instagram Login.messaging_policy_enforcementeresponse_feedback: apenas na coluna da Instagram Messaging API da Meta.- mentions como campo próprio: o Facebook Login e o Unified Login listam-no, com
instagram_manage_comments, enquanto o Instagram Login integra as menções em comments.
Como se subscrevem os campos?
Em dois sítios. No painel da aplicação, nas definições de webhook do produto Instagram, guarde o URL de callback e o token de verificação, o que dispara o pedido de verificação da Meta, e depois selecione os campos; um novo produto Instagram começa subscrito a oito deles. Depois subscreva cada conta com POST /<IG_ID>/subscribed_apps em graph.instagram.com, com subscribed_fields definido com os campos selecionados no painel, separados por vírgulas.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages,message_reactions
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Cada conta pode receber campos diferentes?
Não. O guia de configuração da Meta diz que os campos não podem ser escolhidos para cada conta de utilizador da aplicação: uma conta recebe os campos escolhidos para a aplicação. subscribed_fields na subscrição da conta deve listar os campos do painel, pelo que o gestor de eventos deve esperar qualquer campo que a aplicação tenha selecionado e decidir pelo conteúdo de cada evento, não pelo que pediu a uma conta.
Como se distinguem os campos numa notificação?
Pela forma da entrada. Os campos de comentários chegam num array changes, cada alteração indicando o seu campo. Os campos de mensagens chegam num array messaging sem nome de campo, e a chave ao lado de sender, recipient e timestamp distingue-os:
- changes[].field: comments ou
live_comments, com o comentário em value. - message: messages, incluindo os ecos das mensagens da própria conta, que trazem
is_echodefinido como true. - reaction:
message_reactions. postback:messaging_postbacks. read:messaging_seen.message_edit:message_edit. - referral ao lado de sender:
messaging_referral. Um referral dentro de message pertence a messages, vindo de uma nova conversa ou de um anúncio Click-to-Direct. pass_thread_control,take_thread_controlourequest_thread_control:messaging_handover, tal como a referência de webhooks da Meta os lista.
Que campos subscreve a easyCoexistence?
comments, messages e mentions, a lista com que cada conta do Instagram é subscrita quando se liga. Com o Instagram Login as menções vêm dentro de comments, pelo que a subscrição cobre comentários e mensagens diretas, com os ecos, as respostas a Stories, as menções em Stories e os anexos entre as mensagens diretas. Os outros campos da tabela são entregues pela Meta a uma aplicação subscrita a eles e não fazem parte da subscrição de uma ligação. Quando um endpoint é definido com set_social_webhook_destination ou com a Partner API, a easyCoexistence verifica a assinatura da Meta, responde logo à Meta e envia por POST cada entrada da conta para ele:
- platform e
external_id: instagram, e o ID do Instagram da conta, igual a entry.id. account_id: o ID da ligação na easyCoexistence, o que as ferramentas MCP usam.- entry: a entrada da Meta para a conta, sem alterações. O campo object da Meta e o seu cabeçalho X-Hub-Signature-256 não são transmitidos.
- X-EC-Signature: t=<unix>,v1=<hex>, um HMAC-SHA256 do timestamp, de um ponto e do corpo bruto, com a chave secreta da própria conta.
- Entrega: uma tentativa de até 8 segundos, sem seguir redirecionamentos, sem cópia guardada e sem voltar a tentar.
Erros comuns
- Esperar um campo mentions com Instagram Login. A Meta integra as menções na notificação de comentários, pelo que um gestor ligado ao campo mentions nunca é executado.
- Assumir que uma conta recebe apenas os campos que a sua própria subscrição indicou. A Meta entrega os campos escolhidos para a aplicação, pelo que deve decidir pelo conteúdo de cada evento.
- Tratar message.referral e um referral de nível superior como um só evento. O primeiro vem em messages; o segundo é messaging_referral, para um link ig.me aberto numa conversa já existente.
- Esperar por story_insights com Instagram Login. A Meta assinala-o como indisponível aí, pelo que deve ler as métricas de uma Story no endpoint de insights enquanto estiver ativo.
Os eventos não são guardados por defeito; uma conta com uma automatização ativa guarda as suas DM e comentários durante 7 dias. Defina o endpoint com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com a Partner API. 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
O Instagram Login tem um campo de webhook para menções?
Não há um campo separado. A Meta inclui as menções na notificação de comments para o Instagram Login; mentions é um campo próprio com o Facebook Login e o Unified Login.
O story_insights está disponível com o Instagram Login?
Não. A tabela de campos da Meta assinala-o como indisponível para o Instagram Login, e a referência de media insights diz que o webhook de insights não é suportado aí.
Que permissões precisa o webhook de mensagens do Instagram?
instagram_business_basic e instagram_business_manage_messages, com Advanced Access, que o guia de configuração da Meta indica para os webhooks do Instagram Login.
Quando é que a Meta adicionou o webhook message_edit para o Instagram?
A 10 de setembro de 2025, para o Business Login for Instagram e o Facebook Login for Business. Uma edição chega no array messaging sob a chave message_edit.
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