Campos de webhook do Instagram: a lista completa
Para uma conta profissional no 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 exemplos da Meta incluem também message_edit. Cada um exige instagram_business_basic mais instagram_business_manage_comments ou, para a maioria dos campos de mensagem, instagram_business_manage_messages. story_insights não é oferecido com o Instagram Login.
O easyCoexistence inscreve cada conta do Instagram conectada em comments, messages e mentions, e encaminha esses eventos ao seu endpoint HTTPS assim que chegam, assinados com o segredo daquela conta.
Campos com que um novo produto Instagram no App Dashboard começa inscrito, entre eles comments, messages e message_reactions.
Os campos são selecionados para o app, não por conta: uma conta recebe os campos que o app selecionou.
Nível de acesso que o guia de configuração da Meta lista para webhooks do Instagram Login, e que exige para as notificações de comments e live_comments.
Marcado como indisponível para o 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 o Business Login for Instagram e o Facebook Login for Business.
Quais campos de webhook o Instagram Login oferece?
Estes, da tabela de campos da Meta, com o que dispara cada um tirado dos seus exemplos e da referência de webhook. Cada campo também precisa 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.
Quais 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 do Instagram Login, então um app com Instagram Login não os recebe, e mais um campo existe apenas fora dele:
story_insights: as métricas de um Story quando ele expira, com Facebook Login ou Unified Login einstagram_manage_insights. A referência de insights de mídia da Meta diz que o webhook de insights não é suportado com o Instagram Login.messaging_policy_enforcementeresponse_feedback: apenas na coluna da API de Mensagens do Instagram da Meta.- mentions como campo próprio: o Facebook Login e o Unified Login o listam, com
instagram_manage_comments, enquanto o Instagram Login incorpora as menções em comments.
Como você se inscreve nos campos?
Em dois lugares. No App Dashboard, em configurações de webhook do produto Instagram, salve a URL de callback e o token de verificação, o que dispara a requisição de verificação da Meta, e depois selecione os campos; um novo produto Instagram começa inscrito em oito deles. Em seguida, inscreva cada conta com POST /<IG_ID>/subscribed_apps em graph.instagram.com, com subscribed_fields definido como os campos selecionados no dashboard, 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 selecionados por conta de usuário do app: uma conta recebe os campos selecionados para o app. O subscribed_fields da inscrição da conta deve listar os campos do dashboard, então um handler deve esperar qualquer campo que o app selecionou e decidir pelo que cada evento contém, não pelo que pediu para uma conta.
Como distinguir os campos em uma notificação?
Pela forma da entrada. Os campos de comentário chegam em um array changes, e cada change indica seu campo. Os campos de mensagem chegam em um array messaging sem nome de campo, e a chave ao lado de sender, recipient e timestamp os diferencia:
- changes[].field: comments ou
live_comments, com o comentário em value. - message: messages, incluindo ecos das próprias mensagens da 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, como a referência de webhook da Meta os lista.
Quais campos o easyCoexistence inscreve?
comments, messages e mentions, a lista com que cada conta do Instagram é inscrita ao se conectar. Com o Instagram Login, as menções vêm dentro de comments, então a inscrição cobre comentários e mensagens diretas, com ecos, respostas a Stories, menções em Stories e anexos entre as mensagens diretas. Os demais campos da tabela são entregues pela Meta a um app inscrito neles e não fazem parte da inscrição de uma conexão. Depois que um endpoint é definido com set_social_webhook_destination ou pela Partner API, o easyCoexistence verifica a assinatura da Meta, responde à Meta de imediato e envia por POST cada entrada da conta para ele:
- platform e
external_id: instagram, e o ID da conta no Instagram, igual a entry.id. account_id: o ID da conexão no easyCoexistence, aquele que as ferramentas MCP recebem.- entry: a entrada da Meta para a conta, sem alterações. O campo object da Meta e o cabeçalho X-Hub-Signature-256 não são repassados.
- X-EC-Signature: t=<unix>,v1=<hex>, um HMAC-SHA256 do timestamp, um ponto e o corpo bruto, com a chave secreta própria da conta.
- Entrega: uma tentativa de até 8 segundos, sem seguir redirecionamentos, sem cópia guardada e sem repetir a entrega.
Erros comuns
- Esperar um campo mentions com o Instagram Login. A Meta incorpora as menções na notificação de comments, então um handler ligado ao campo mentions nunca roda.
- Supor que uma conta recebe apenas os campos que a própria inscrição indicou. A Meta entrega os campos selecionados para o app, então ramifique pelo que cada evento contém.
- Tratar message.referral e um referral de nível superior como um único evento. O primeiro vem em messages; o segundo é messaging_referral, para um link ig.me aberto em uma conversa existente.
- Esperar story_insights com o Instagram Login. A Meta o marca como indisponível ali, então leia as métricas de um Story no endpoint de insights enquanto o Story ainda estiver disponível.
Os eventos não são armazenados por padrão; uma conta com automação ativada mantém suas DMs e comentários por 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 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
O Instagram Login tem um campo de webhook de menções?
Não como 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.
story_insights está disponível com o Instagram Login?
Não. A tabela de campos da Meta o marca como indisponível para o Instagram Login, e a referência de insights de mídia diz que o webhook de insights não é suportado ali.
Quais permissões o webhook de mensagens do Instagram exige?
instagram_business_basic e instagram_business_manage_messages, com Advanced Access, que o guia de configuração da Meta lista para webhooks do Instagram Login.
Quando a Meta adicionou o webhook message_edit para o Instagram?
Em 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 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