Webhook de comentários do Instagram: o payload, campo por campo
O campo comments do webhook do Instagram avisa um app quando alguém comenta, ou responde a um comentário, em uma mídia de uma conta profissional, incluindo Reels. A Meta envia um item de changes com field igual a comments, cujo value traz o id e o texto do comentário, o ID com escopo do Instagram e o username do autor em from, o id e o tipo de produto da mídia, e parent_id quando o comentário é uma resposta.
O easyCoexistence inscreve cada conta do Instagram conectada em comments e encaminha ao seu endpoint HTTPS, assim que chegam, os eventos de comments que a Meta entrega para ela, assinados com o segredo daquela conta e sem guardar cópia.
Presente quando o comentário é uma resposta, com o ID do comentário ao qual ele responde.
Incluído em from quando a conta comenta na própria mídia, ao lado do ID da própria conta.
Campo separado para comentários durante uma transmissão ao vivo; as notificações param quando a transmissão termina.
Obrigatório para as notificações de comments e live_comments; mídia de contas privadas não gera nenhuma.
Prazo para enviar a quem comentou uma única resposta privada, endereçada pelo ID do comentário.
Quando o campo comments dispara?
Quando alguém comenta em uma mídia da conta profissional, ou menciona a conta, depois que o app e a conta estiverem inscritos no campo. Cada comentário é um item de changes na notificação, e estes casos têm o mesmo formato:
- Um novo comentário em um post, Reel, Story ou anúncio, com media.
media_product_typeindicando em que superfície a mídia está. - Uma resposta a um comentário existente, que traz
parent_idcom o ID do comentário ao qual responde. - Um comentário que a conta faz na própria mídia, incluindo as respostas: from.id é o ID da própria conta, e from inclui também
self_ig_scoped_id. - Uma @menção à conta: com o Instagram Login, a Meta inclui as menções na notificação de comments, em vez de usar um campo próprio.
- Um comentário durante uma transmissão ao vivo chega em um campo separado,
live_comments, com o mesmo formato de value, e para quando a transmissão termina.
Como é uma notificação de comentário?
Um POST cujo JSON tem object igual a instagram e um array entry. Cada entry é uma conta profissional: o ID dela, o horário em que a Meta enviou a notificação e um array changes com um item por comentário. Uma resposta em um Reel fica assim:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"parent_id": "<PARENT_COMMENT_ID>",
"text": "<COMMENT_TEXT>",
"from": {
"id": "<INSTAGRAM_SCOPED_ID>",
"username": "<USERNAME>"
},
"media": {
"id": "<MEDIA_ID>",
"media_product_type": "REELS"
}
}
}
]
}
]
}O que significa cada campo?
Os campos que a referência de webhooks da Meta lista para um comentário, de fora para dentro:
- entry[].id: o ID da conta profissional, o
user_idque /me retorna para ela. Indica a qual conta o comentário pertence. - entry[].time: quando a Meta enviou a notificação, como timestamp Unix. Não é quando o comentário foi escrito.
- changes[].field: comments, ou
live_commentspara uma transmissão ao vivo. Confira esse campo antes de ler value. - value.id: o ID do comentário, o que você usa para responder em público ou em privado, ocultar ou excluir o comentário.
- value.text: o texto do comentário, incluído quando o comentário tem texto.
- value.from.id e value.from.username: o ID com escopo do Instagram e o username do autor. value.from.
self_ig_scoped_idaparece quando a própria conta escreveu o comentário. - value.media.id e value.media.
media_product_type: a mídia comentada e a superfície dela; a referência de mídia da Meta lista AD, FEED, STORY e REELS. - value.
parent_id: em uma resposta, o ID do comentário ao qual ela responde. Um comentário de primeiro nível não tem esse campo. - value.media.
ad_id,ad_titleeoriginal_media_id: listados na referência para comentários feitos em um anúncio.
O que o campo comments não informa?
Algumas coisas que um handler poderia esperar ficam de fora do evento ou nunca são enviadas, segundo o guia de configuração e as referências da Meta:
- Comentários em mídia de conta privada: a Meta não envia notificações de comentário nem de menção para eles.
- IDs de álbum: o evento não os inclui, e a Meta orienta consultar o álbum pelo ID do comentário.
- IDs de anúncio para mídia usada em anúncios dinâmicos.
- O horário de criação do comentário: GET /<
COMMENT_ID>?fields=timestamp o retorna em ISO 8601. - Comentários ao vivo depois que a transmissão termina, quando as notificações de mídia ao vivo param.
- Menções em Stories, que a API de menções da Meta não suporta; em vez disso, elas chegam à conta como DMs.
- Eventos passados: a Meta não mantém histórico de notificações para consulta, então guarde o que você precisa à medida que cada uma chega.
Do que o campo comments precisa?
Com o Instagram Login, das permissões instagram_business_basic e instagram_business_manage_comments, e de Advanced Access, que a Meta exige para as notificações de comments e live_comments. O app precisa estar em modo Live e inscrito em comments no App Dashboard, e cada conta precisa ser inscrita por POST /<IG_ID>/subscribed_apps com comments entre os seus subscribed_fields. A Meta recomenda fortemente usar este webhook em vez de fazer polling dos comentários, porque isso poupa o limite de taxa.
Como responder a um comentário a partir do evento?
Com os IDs que ele traz. POST /<COMMENT_ID>/replies com message publica uma resposta visível abaixo do comentário, usando value.id. POST /<IG_ID>/messages com recipient.comment_id igual a value.id envia ao autor uma única resposta privada, em até 7 dias após o comentário ou, em uma Live, enquanto a transmissão durar. from.id é um ID com escopo do Instagram, mas uma DM enviada diretamente a ele falha até que a pessoa mande uma mensagem para a conta, então a resposta privada é o caminho para alcançá-la por DM.
Como o easyCoexistence encaminha um comentário?
Assim que ele chega, depois que um endpoint é definido para a conta com set_social_webhook_destination pelo Claude ou pelo ChatGPT, ou com PUT /channels/:id/webhook na Partner API. O easyCoexistence inscreve cada conta conectada nos campos que trazem seus comentários, menções e DMs, verifica a assinatura da Meta em cada entrega, responde à Meta na hora e faz um POST de cada entry daquela conta para a sua URL HTTPS dentro de um envelope:
- platform e
external_id: instagram, e o ID do Instagram da conta, igual a entry.id. account_id: o ID da conexão no easyCoexistence, o mesmo quelist_social_accountsretorna e que as ferramentas MCP recebem.- entry: o entry da Meta para a conta, sem alterações, então uma entrega em lote vira um POST por entry. O campo object da Meta e o X-Hub-Signature-256 não são repassados.
- Entrega: uma tentativa, aguardando até 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público. Nenhuma cópia é guardada e nenhuma entrega é repetida.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"text": "<COMMENT_TEXT>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"media": { "id": "<MEDIA_ID>", "media_product_type": "FEED" }
}
}
]
}
}O que as regras de comentário para DM fazem com o mesmo evento?
Elas leem o evento junto com o encaminhamento. Uma regra é acionada quando o comentário contém uma das suas palavras-chave, sem diferenciar maiúsculas de minúsculas, em uma publicação escolhida ou em todas, e envia ao autor a DM da regra como resposta privada, além de uma resposta pública, se a regra tiver uma. Comentários da própria conta são ignorados, as automações que começam em um comentário ficam com os que nenhuma regra respondeu, e um comentário respondido por uma regra continua chegando ao seu endpoint. A resposta pública da regra pode voltar como um novo evento de comments vindo da própria conta.
Erros comuns
- Procurar por comment_id. Com o Instagram Login, o ID do comentário está em value.id; comment_id pertence aos payloads das outras configurações de login da Meta.
- Responder aos comentários da própria conta. As respostas dela voltam como eventos de comments com from.id igual a entry.id, e uma automação que responde a elas acaba conversando consigo mesma.
- Ler entry.time como o horário do comentário. Ele registra quando a Meta enviou a notificação; o campo timestamp do próprio comentário diz quando ele foi escrito.
- Esperar comentários de Live no campo comments. Eles chegam em live_comments, que precisa de uma inscrição própria e para de enviar quando a transmissão termina.
As regras de comentário para DM e as automações respondem a esses mesmos comentários 24 horas por dia. De R$ 29,90 a R$ 3,90 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os 3 primeiros 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 webhook de comentários do Instagram inclui respostas a comentários?
Sim. Uma resposta chega como um evento de comments próprio, com parent_id contendo o ID do comentário ao qual ela responde.
Comentários em Reels disparam o webhook de comentários do Instagram?
Sim. Um comentário em um Reel chega no campo comments como um comentário em post, e media.media_product_type diferencia os dois.
Por que o webhook de comentários do Instagram não está disparando?
Na maioria das vezes, o app não está em modo Live ou não tem Advanced Access, a conta nunca foi inscrita por /subscribed_apps, a mídia pertence a uma conta privada ou o comentário foi feito em uma Live, que usa live_comments.
O webhook de comentários traz o username de quem comentou?
Sim. value.from traz o username da pessoa junto com o ID com escopo do Instagram, então não é preciso nenhuma chamada extra para mostrar quem comentou.
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