EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Assinando uma Página do Facebook a webhooks: o edge subscribed_apps

Uma Página do Facebook é assinada aos webhooks de um app com POST /{page-id}/subscribed_apps, passando subscribed_fields, como feed,messages, e um token de acesso da Página de alguém com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, com as permissões pages_manage_metadata e pages_show_list concedidas. A Meta envia os eventos de um campo só quando o app também assina esse campo; GET lista a assinatura e DELETE a remove.

O easyCoexistence assina cada Página que você conecta a feed, messages e mention por meio do subscribed_apps, desassina quando você a remove e encaminha os eventos da Página para o seu endpoint HTTPS, assinado com um segredo próprio dessa Página, a partir de um único conector MCP ou da Partner API.

Both levels

Só os campos assinados tanto no nível da Página quanto no do app geram webhooks; uma Página pode listar mais do que o app.

CREATE_CONTENT, MANAGE or MODERATE

Tarefas da Página, uma das quais a pessoa por trás do token precisa para ler ou criar uma assinatura.

messaging_success

Retornado junto com success quando um app remove a assinatura de webhook de uma Página com DELETE.

App access token

O que /{app-id}/subscriptions exige para ler, criar ou excluir a assinatura no nível do app.

1 hour

Sobre as entregas com falha do Messenger antes de a Meta desassinar o app da Página, até que ele assine novamente.

O que faz o edge subscribed_apps?

Ele instala o app na Página e define quais campos de webhook da Página o app recebe. A Meta só envia notificações enquanto a Página tiver o app instalado e não tiver desativado a plataforma de apps nas configurações, e somente para campos assinados nos dois níveis: o da Página, por este edge, e o do app, definido no App Dashboard ou em /{app-id}/subscriptions. Uma Página pode ser assinada a mais campos do que o app.

Como assinar uma Página?

Com um POST no edge, passando subscribed_fields com os campos separados por vírgula, e o token de acesso da Página. Uma chamada bem-sucedida retorna success true, e uma chamada que lista messages também precisa de pages_messaging no token:

Subscribing a Page to three fields
POST https://graph.facebook.com/{page-id}/subscribed_apps
  ?subscribed_fields=feed,messages,mention
  &access_token=<PAGE_ACCESS_TOKEN>

{ "success": true }

Qual token, tarefas e permissões ele precisa?

Um token de acesso da Página, que vincula a chamada a uma única Página, de alguém que possa agir nessa Página. As referências e guias da Meta definem estes requisitos:

  • Qualquer campo: uma pessoa com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, e pages_manage_metadata com pages_show_list.
  • messages e os demais campos do Messenger: pages_messaging também, em um token de alguém que possa executar a tarefa MESSAGING.
  • leadgen: a tarefa ADVERTISE, com leads_retrieval, pages_read_engagement e ads_management.
  • Ler a assinatura com GET exige as mesmas tarefas e permissões que criá-la.

Qual nível de acesso os campos precisam?

Acesso Avançado, para Páginas e pessoas fora dos papéis do próprio app. Com Acesso Padrão, as notificações do Messenger vêm apenas de pessoas com algum papel no app, como administradores, desenvolvedores e testers; o Acesso Avançado, concedido por permissão pela Análise do app e exigindo a Verificação da empresa, as libera para os clientes do app. O guia do Messenger da Meta também lista a publicação do app entre os pré-requisitos.

O que é a assinatura no nível do app?

A outra metade: os campos que o próprio app escuta, com sua URL de callback. Ela é definida no App Dashboard ou com POST /{app-id}/subscriptions e um token de acesso do app, passando object=page, callback_url, fields, include_values e verify_token, o que dispara a requisição de verificação da Meta. GET nesse mesmo edge mostra o callback_url de cada objeto, seus campos e se a assinatura está ativa; um novo POST altera os campos sem sobrescrever os demais, e DELETE remove todos eles ou apenas os campos indicados.

Como verificar o que uma Página está assinada?

Com um GET no mesmo edge e o token da Página. O array data lista cada app instalado na Página, com nome, ID e subscribed_fields, e volta vazio quando a Página não tem apps instalados:

Reading a Page's subscriptions
GET https://graph.facebook.com/{page-id}/subscribed_apps
  ?access_token=<PAGE_ACCESS_TOKEN>

{
  "data": [
    {
      "category": "Business",
      "link": "https://example.com/app",
      "name": "<APP_NAME>",
      "id": "<APP_ID>",
      "subscribed_fields": ["feed", "messages", "mention"]
    }
  ]
}

Como remover uma assinatura?

Com DELETE /{page-id}/subscribed_apps, que desvincula o app da Página; um app pode remover a própria assinatura com um token de acesso do app, e a resposta traz success e messaging_success. A Meta também a remove por conta própria: após uma hora de entregas falhas do Messenger, o app é desassinado da Página e precisa assinar de novo quando o endpoint voltar a funcionar.

O que o easyCoexistence faz na conexão?

Ele assina cada Página que a pessoa escolhe, logo após salvar o token dessa Página: POST /{page-id}/subscribed_apps com subscribed_fields definido como feed,messages,mention. Se a Meta recusar, a Página continua conectada e list_social_accounts mostra o motivo em last_error. Ao remover a Página, o DELETE /{page-id}/subscribed_apps é enviado antes de o token ser descartado, e nenhuma ferramenta alcança caminhos subscribed_apps e de token, de modo que a assinatura é gerida somente pelo easyCoexistence.

Erros comuns

  • Chamar o edge com um token de acesso de usuário. Ele exige o token de acesso da Página que está sendo assinada.
  • Assinar a Página sem assinar o app. Um campo só chega ao callback quando a assinatura do próprio app também o inclui.
  • Esquecer pages_messaging ao assinar messages. A Meta exige a permissão, em um token de alguém que possa executar a tarefa MESSAGING.
  • Esquecer de assinar de novo após uma interrupção. Uma hora de entregas falhas do Messenger desassina o app, e os eventos param até que o POST seja enviado novamente.
Fazendo isso com o EasyCoexistence

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

Preciso assinar cada Página separadamente?

Sim. O subscribed_apps funciona por Página, com o token da própria Página, enquanto a assinatura no nível do app para o objeto page vale para as Páginas que instalaram o app.

Por que o subscribed_apps retorna o erro 200?

A Meta classifica o 200 como erro de permissão para este edge. Verifique se o token tem pages_manage_metadata e pages_show_list e se vem de alguém com CREATE_CONTENT, MANAGE ou MODERATE.

Dá para assinar uma Página pelo Graph API Explorer?

Sim. O guia da Meta escolhe o app, obtém um token de usuário com pages_manage_metadata, troca-o pelo token da Página e envia o POST para {page-id}/subscribed_apps.

Posso adicionar campos de webhook a uma Página conectada ao easyCoexistence?

Não pelas suas ferramentas: nenhuma alcança caminhos subscribed_apps, e a Página continua assinada a feed, messages e mention, os campos que o easyCoexistence encaminha.

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