Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

parent_id

Presente quando o comentário é uma resposta, com o ID do comentário a que responde.

self_ig_scoped_id

Acrescentado a from quando a conta comenta nos seus próprios conteúdos, junto ao ID da própria conta.

live_comments

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

Advanced Access

Obrigatório para as notificações comments e live_comments; conteúdos de contas privadas não geram nenhuma.

7 days

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_type a indicar em que superfície está o conteúdo.
  • Uma resposta a um comentário existente, que traz parent_id com 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:

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 indica para um comentário, de fora para dentro:

  • entry[].id: o ID da conta profissional, o user_id que /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_comments para 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_id aparece 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_title e original_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 devolve list_social_accounts e 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.
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 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.
Fazer isto com a EasyCoexistence

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