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.
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.
Tarefas da Página, uma das quais a pessoa por trás do token precisa para ler ou criar uma assinatura.
Retornado junto com success quando um app remove a assinatura de webhook de uma Página com DELETE.
O que /{app-id}/subscriptions exige para ler, criar ou excluir a assinatura no nível do app.
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:
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, epages_manage_metadatacompages_show_list. - messages e os demais campos do Messenger:
pages_messagingtambém, em um token de alguém que possa executar a tarefa MESSAGING. - leadgen: a tarefa ADVERTISE, com
leads_retrieval,pages_read_engagementeads_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:
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.
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