Webhook de comentários do Instagram: o payload, campo a campo
O campo comments do webhook do Instagram avisa uma aplicação quando alguém comenta, ou responde a um comentário, nos conteúdos de uma conta profissional, incluindo os Reels. A Meta envia uma alteração com field igual a comments, cujo value traz o ID e o texto do comentário, o ID de âmbito Instagram e o nome de utilizador do autor em from, o ID e o tipo de produto do conteúdo em media, e parent_id quando o comentário é uma resposta.
O easyCoexistence subscreve cada conta do Instagram ligada a comments e encaminha para o seu endpoint HTTPS os eventos comments que a Meta entrega para ela, à medida que chegam, assinados com o segredo dessa conta e sem guardar cópias.
Presente quando o comentário é uma resposta, com o ID do comentário a que responde.
Acrescentado a from quando a conta comenta nos seus próprios conteúdos, junto ao ID da própria conta.
Campo separado para comentários durante uma transmissão em direto; as notificações param quando a transmissão termina.
Obrigatório para as notificações comments e live_comments; conteúdos de contas privadas não geram nenhuma.
Tempo restante para enviar a um comentador uma resposta privada, identificado pelo ID do comentário.
Quando é que o campo comments é acionado?
Quando alguém comenta num conteúdo que a conta profissional possui, ou menciona a conta, depois de a aplicação e a conta estarem ambas subscritas ao campo. Cada comentário é uma alteração na notificação, e estes casos partilham a mesma forma:
- Um novo comentário numa publicação, num Reel, numa Story ou num anúncio, com media.
media_product_typea indicar em que superfície está o conteúdo. - Uma resposta a um comentário existente, que traz
parent_idcom o ID do comentário a que responde. - Um comentário que a conta faz nos seus próprios conteúdos, incluindo as respostas: from.id é o ID da própria conta, e from acrescenta
self_ig_scoped_id. - Uma @menção à conta: com o Instagram Login, a Meta inclui as menções na notificação de comentários em vez de um campo próprio.
- Um comentário durante uma transmissão em direto chega num campo separado,
live_comments, com a mesma forma de valor, e deixa de chegar quando a transmissão termina.
Como é uma notificação de comentários?
Um POST cujo JSON tem object igual a instagram e um array entry. Cada entrada corresponde a uma conta profissional: o seu ID, a hora a que a Meta enviou a notificação, e um array changes com uma alteração por comentário. Uma resposta num Reel tem este aspeto:
{
"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 indica para um comentário, de fora para dentro:
- entry[].id: o ID da conta profissional, o
user_idque /me devolve para ela. Indica-lhe a que conta pertence o comentário. - entry[].time: quando a Meta enviou a notificação, como timestamp Unix. Não é o momento em que o comentário foi escrito.
- changes[].field: comments, ou
live_commentspara uma transmissão em direto. Verifique-o antes de ler value. - value.id: o ID do comentário, aquele a que responde em público ou em privado, que oculta ou elimina.
- value.text: o texto do comentário, incluído quando o comentário tem texto.
- value.from.id e value.from.username: o ID de âmbito Instagram e o nome de utilizador 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: o conteúdo comentado e a sua superfície; a referência de conteúdos da Meta indica AD, FEED, STORY e REELS. - value.
parent_id: numa resposta, o ID do comentário a que responde. Um comentário de primeiro nível não tem nenhum. - value.media.
ad_id,ad_titleeoriginal_media_id: indicados na referência para comentários feitos num anúncio.
O que o campo comments não comunica?
Algumas coisas que o código que trata o evento 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 conteúdos de uma conta privada: a Meta não envia notificações de comentários nem de menções para eles.
- IDs de álbuns: o evento não os inclui, e a Meta indica que se procure o álbum com o ID do comentário.
- IDs de anúncios para conteúdos usados em anúncios dinâmicos.
- A hora de criação do comentário: GET /<
COMMENT_ID>?fields=timestamp devolve-a em ISO 8601. - Comentários em direto depois de a transmissão terminar, quando as notificações de conteúdos em direto param.
- Menções em Stories, que a API de menções da Meta não suporta; chegam à conta como DMs.
- Eventos passados: a Meta não guarda um histórico de notificações para consultar, por isso guarde o necessário à medida que cada uma chega.
O que o campo comments precisa?
Com o Instagram Login, as permissões instagram_business_basic e instagram_business_manage_comments, e o Advanced Access, que a Meta exige para as notificações comments e live_comments. A aplicação tem de estar Live e subscrita a comments no App Dashboard, e cada conta tem de ser subscrita através de POST /<IG_ID>/subscribed_apps com comments entre os seus subscribed_fields. A Meta recomenda vivamente este webhook em vez de consultar os comentários periodicamente, porque poupa o limite de pedidos.
Como responder a um comentário a partir do evento?
Com os IDs que traz. POST /<COMMENT_ID>/replies com uma message publica uma resposta pública por baixo do comentário, usando value.id. POST /<IG_ID>/messages com recipient.comment_id igual a value.id envia ao autor uma resposta privada, no prazo de 7 dias após o comentário, ou enquanto durar a transmissão em direto. from.id é um ID de âmbito Instagram, mas uma DM enviada diretamente para ele falha até a pessoa ter escrito à conta, por isso a resposta privada é a forma de a contactar por DM.
Como é que o easyCoexistence encaminha um comentário?
Assim que houver um endpoint definido para a conta, com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com PUT /channels/:id/webhook na Partner API. O easyCoexistence subscreve cada conta ligada aos campos que transportam os seus comentários, menções e DMs, verifica a assinatura da Meta em cada entrega, responde de imediato à Meta, e envia por POST cada entrada dessa conta para o seu 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 ligação no easyCoexistence, o que devolvelist_social_accountse que as ferramentas MCP usam.- entry: a entrada da Meta para a conta, sem alterações, pelo que uma entrega em lote se torna um POST por entrada. O object da Meta e o X-Hub-Signature-256 não são transmitidos.
- Entrega: uma única tentativa, com espera até 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público. Não fica guardada nenhuma cópia e nada é repetido.
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 fazem as regras de comentário para DM com o mesmo evento?
Leem-no em paralelo com o encaminhamento. Uma regra aplica-se quando o comentário contém uma das suas palavras-chave, sem distinguir maiúsculas, numa 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. Os comentários feitos pela própria conta são ignorados, as automações que começam num comentário ficam com os comentários a que nenhuma regra respondeu, e um comentário a que uma regra respondeu continua a chegar ao seu endpoint. A resposta pública da regra pode voltar como um novo evento comments da própria conta.
Erros comuns
- Procurar 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 chegam como eventos comments com from.id igual a entry.id, e uma automação que lhes responde acaba a responder a si mesma.
- Ler entry.time como a hora do comentário. Regista quando a Meta enviou a notificação; o campo timestamp do próprio comentário indica quando foi escrito.
- Esperar comentários em direto no campo comments. Chegam em live_comments, que precisa de subscrição própria e deixa de chegar quando a transmissão termina.
As regras de comentário para DM e as automações respondem aos mesmos comentários 24 horas por dia. De US$ 9 até US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
O webhook de comentários do Instagram inclui as respostas aos comentários?
Sim. Uma resposta chega como um evento comments próprio, com parent_id a conter o ID do comentário a que responde.
Os comentários nos Reels acionam o webhook de comentários do Instagram?
Sim. Um comentário num Reel chega no campo comments como um comentário numa publicação, e media.media_product_type distingue os dois.
Porque é que o meu webhook de comentários do Instagram não dispara?
Na maioria das vezes, a aplicação não está Live ou não tem o Advanced Access, a conta nunca foi subscrita através de /subscribed_apps, o conteúdo pertence a uma conta privada, ou o comentário foi feito numa transmissão em direto, que usa live_comments.
O webhook de comentários inclui o nome de utilizador de quem comenta?
Sim. value.from traz o nome de utilizador da pessoa junto ao seu ID de âmbito Instagram, pelo que não é preciso nenhuma chamada extra para mostrar quem comentou.
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