EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

parent_id

Presente quando o comentário é uma resposta, com o ID do comentário ao qual ele responde.

self_ig_scoped_id

Incluído em from quando a conta comenta na própria mídia, ao lado do ID da própria conta.

live_comments

Campo separado para comentários durante uma transmissão ao vivo; as notificações param quando a transmissão termina.

Advanced Access

Obrigatório para as notificações de comments e live_comments; mídia de contas privadas não gera nenhuma.

7 days

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_type indicando em que superfície a mídia está.
  • Uma resposta a um comentário existente, que traz parent_id com 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:

A comments notification, as Meta sends it
{
  "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_id que /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_comments para 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_id aparece 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_title e original_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 que list_social_accounts retorna 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.
A forwarded comment, headers included
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.
Fazendo isso com o EasyCoexistence

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