Subscrever uma Página do Facebook a webhooks: o edge subscribed_apps
Uma Página do Facebook fica subscrita aos webhooks de uma app com POST /{page-id}/subscribed_apps, enviando subscribed_fields como feed,messages e um token de acesso à 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 só envia os eventos de um campo quando a app também o subscreve; GET lista a subscrição e DELETE remove-a.
O easyCoexistence subscreve cada Página ligada a feed, messages e mention através de subscribed_apps, cancela a subscrição quando a Página é removida e encaminha os eventos da Página para o seu endpoint HTTPS, assinados com um segredo próprio dessa Página, a partir de um único conector MCP ou da Partner API.
Só os campos subscritos ao nível da Página e ao nível da app geram webhooks; uma Página pode listar mais campos do que a app.
Tarefas da Página, uma das quais a pessoa por trás do token precisa para ler ou criar uma subscrição.
Devolvido junto de success quando uma app remove a sua subscrição de webhook de uma Página com DELETE.
O que /{app-id}/subscriptions exige para ler, criar ou eliminar a subscrição ao nível da app.
Das entregas falhadas do Messenger, antes de a Meta remover a subscrição da app na Página até que esta volte a subscrever.
O que faz o edge subscribed_apps?
Instala a app na Página e define quais dos campos de webhook da Página a app recebe. A Meta só envia notificações enquanto a Página tiver a app instalada e não tiver desativado a plataforma de apps nas suas definições, e apenas para campos subscritos aos dois níveis: o da Página, através deste edge, e o da app, definido no painel da app ou através de /{app-id}/subscriptions. Uma Página pode estar subscrita a mais campos do que a app.
Como se subscreve uma Página?
Com um POST para o edge, com subscribed_fields a listar os campos separados por vírgulas, e o token de acesso da Página. Uma chamada bem-sucedida devolve success true, e uma chamada que liste messages precisa também 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 }Que token, tarefas e permissões são necessários?
Um token de acesso à Página, que liga a chamada a uma só Página, de alguém que possa agir nessa Página. As referências e os 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 outros campos do Messenger:
pages_messagingtambém, num token de alguém que possa executar a tarefa MESSAGING. - leadgen: a tarefa ADVERTISE, com
leads_retrieval,pages_read_engagementeads_management. - Ler a subscrição com GET exige as mesmas tarefas e permissões que criá-la.
Que nível de acesso precisam os campos?
Advanced Access, para Páginas e pessoas fora dos papéis próprios da app. Com Standard Access, as notificações do Messenger chegam apenas de pessoas com um papel na app, como os seus administradores, programadores e testadores; o Advanced Access, concedido permissão a permissão através da App Review e que exige a Business Verification, abre-as aos clientes da app. O guia do Messenger da Meta lista também a publicação da app entre os pré-requisitos.
O que é a subscrição ao nível da app?
A outra metade: os campos que a própria app escuta, com o seu callback URL. Define-se no painel da app ou com POST /{app-id}/subscriptions e um token de acesso da app, passando object=page, callback_url, fields, include_values e verify_token, o que desencadeia o pedido de verificação da Meta. GET no mesmo edge mostra o callback_url, os campos de cada objeto e se a subscrição está ativa; um novo POST altera os campos sem sobrescrever os outros, e DELETE remove todos ou apenas os campos indicados.
Como se verifica o que uma Página tem subscrito?
Com um GET no mesmo edge e o token da Página. O array data lista cada app que a Página tem instalada, com o seu nome, ID e subscribed_fields, e vem vazio quando a Página não tem apps instaladas:
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 se remove uma subscrição?
Com DELETE /{page-id}/subscribed_apps, que desassocia a app da Página; uma app pode remover a sua própria subscrição com um token de acesso da app, e a resposta contém success e messaging_success. A Meta também a remove por iniciativa própria: após uma hora de entregas falhadas do Messenger, a subscrição da app à Página é cancelada e a app tem de voltar a subscrever quando o seu endpoint voltar a funcionar.
O que faz o easyCoexistence ao ligar?
Subscreve cada Página que a pessoa escolhe, logo a seguir a guardar 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 fica ligada e list_social_accounts mostra o motivo em last_error. Remover a Página envia DELETE /{page-id}/subscribed_apps antes de o token ser descartado, e nenhuma ferramenta alcança os caminhos subscribed_apps e token, pelo que a subscrição é gerida apenas pelo easyCoexistence.
Erros comuns
- Chamar o edge com um token de acesso de utilizador. Exige o token de acesso da Página que vai ser subscrita.
- Subscrever a Página mas não a app. Um campo só chega ao callback se a subscrição da própria app também o incluir.
- Esquecer pages_messaging ao subscrever messages. A Meta exige-a, num token de alguém que possa executar a tarefa MESSAGING.
- Esquecer de voltar a subscrever depois de uma falha. Uma hora de entregas falhadas do Messenger cancela a subscrição da app, e os eventos param até que o POST seja enviado de novo.
De US$ 9 a US$ 0.75 por ligação por mês, com o valor a baixar à medida que se acrescentam ligações, e os primeiros 3 dias grátis.
Perguntas frequentes
Preciso de subscrever cada Página separadamente?
Sim. subscribed_apps funciona por Página, com o token dessa própria Página, enquanto a subscrição ao nível da app para o objeto page se aplica às Páginas que instalaram a app.
Porque é que subscribed_apps devolve o erro 200?
A Meta classifica o 200 como erro de permissões neste edge. Confirme que o token tem pages_manage_metadata e pages_show_list e que vem de alguém com CREATE_CONTENT, MANAGE ou MODERATE.
Pode subscrever-se uma Página a partir do Graph API Explorer?
Sim. O guia da Meta escolhe a app, obtém um token de utilizador com pages_manage_metadata, troca-o pelo token da Página e envia o POST para {page-id}/subscribed_apps.
Posso acrescentar campos de webhook a uma Página ligada ao easyCoexistence?
Não através das suas ferramentas: nenhuma alcança os caminhos subscribed_apps, e a Página continua subscrita a feed, messages e mention, os campos que o easyCoexistence encaminha.
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