API de Páginas do Facebook em Python e Node.js: exemplos práticos
Python e Node.js chamam a API de Páginas do Facebook como pedidos HTTPS simples para graph.facebook.com/v26.0, com o token de acesso da Página: POST /{page-id}/feed e /{page-id}/photos publicam, /{post-id}/comments lê e responde a comentários, POST /{page-id}/messages responde no Messenger, GET /{page-id}/insights lê métricas, e um HMAC-SHA256 do corpo bruto valida o X-Hub-Signature-256 em cada webhook.
A easyCoexistence dá a uma Página ligada estas tarefas como ferramentas MCP, desde publish_facebook_post e reply_to_comment até send_social_dm e get_social_insights, encaminha os seus eventos assinados com X-EC-Signature e dá ao seu próprio código o ID da Página e a base da API através de get_social_credentials.
O parâmetro text de uma foto da Página; a referência de fotos da Meta marca message como obsoleto ali.
Cabeçalho de resposta cujo estimated_time_to_regain_access indica os minutos até as chamadas limitadas voltarem a funcionar.
O messaging_type de uma resposta a uma mensagem que a Página recebeu, enviada dentro da janela de 24 horas.
Como uma resposta privada endereça a pessoa que comentou, através do mesmo endpoint /{page-id}/messages.
O que os exemplos precisam antes de serem executados?
Um ID de Página e o token de acesso dessa Página, lido em /me/accounts com um token de utilizador de longa duração, mais Python 3 com requests, ou Node.js 18 ou posterior, cujo fetch integrado não precisa de pacote. Cada tarefa precisa também da respetiva permissão no token e da sua tarefa na Página, e os exemplos chamam a Graph API v26.0:
Como publicar uma publicação e uma foto em Python?
Com um auxiliar que os exemplos seguintes reutilizam: graph() acrescenta o token da Página, envia os parâmetros GET na query string e os campos POST em JSON, como os exemplos da própria Meta, e converte o objeto de erro da Meta num GraphError com code e error_subcode. Só volta a tentar os códigos temporários e de limite de taxa, durante o tempo que X-Business-Use-Case-Usage indicar quando esse cabeçalho aparecer, e lança os restantes de imediato.
import json, os, time
import requests
GRAPH = "https://graph.facebook.com/v26.0"
PAGE_ID = os.environ["PAGE_ID"]
PAGE_TOKEN = os.environ["PAGE_TOKEN"] # the Page's own token, from /me/accounts
RETRY = {1, 2, 4, 17, 32, 613, 80001} # temporary or rate limited
class GraphError(Exception):
def __init__(self, err):
super().__init__(err.get("message"))
self.code, self.subcode = err.get("code"), err.get("error_subcode")
def wait_seconds(response, attempt):
usage = json.loads(response.headers.get("x-business-use-case-usage", "{}"))
minutes = [u.get("estimated_time_to_regain_access", 0) for v in usage.values() for u in v]
return max([60 * m for m in minutes] + [30 * 2 ** attempt])
def graph(method, path, retries=3, **fields):
fields["access_token"] = PAGE_TOKEN
send = {"params": fields} if method == "GET" else {"json": fields}
for attempt in range(retries + 1):
response = requests.request(method, f"{GRAPH}/{path}", timeout=30, **send)
body = response.json()
if "error" not in body:
return body
err = GraphError(body["error"])
if err.code not in RETRY or attempt == retries:
raise err
time.sleep(wait_seconds(response, attempt))
post = graph("POST", f"{PAGE_ID}/feed", message="Open until 11pm this Friday.")
photo = graph("POST", f"{PAGE_ID}/photos",
url="https://example.com/menu.jpg", caption="This week's menu")
print(post["id"], photo["post_id"])Como se publicam em Node.js?
Com o mesmo auxiliar em Node.js 18 ou posterior, guardado num ficheiro .mjs para que o top-level await funcione, e o fetch integrado no lugar de uma biblioteca cliente. A chamada da foto envia url e caption, o campo text do edge photos; a Meta responde com o id da foto e o post_id da publicação da Página que contém a foto, enquanto a chamada ao feed responde apenas com o id da publicação.
// Node.js 18 or later, saved as an .mjs file: fetch and top-level await are built in.
const GRAPH = "https://graph.facebook.com/v26.0";
const { PAGE_ID, PAGE_TOKEN } = process.env; // the Page's own token, from /me/accounts
const RETRY = new Set([1, 2, 4, 17, 32, 613, 80001]); // temporary or rate limited
class GraphError extends Error {
constructor(err) {
super(err.message);
this.code = err.code;
this.subcode = err.error_subcode;
}
}
function waitMs(response, attempt) {
const usage = JSON.parse(response.headers.get("x-business-use-case-usage") ?? "{}");
const minutes = Object.values(usage).flat().map((u) => u.estimated_time_to_regain_access ?? 0);
return Math.max(30_000 * 2 ** attempt, ...minutes.map((m) => m * 60_000));
}
async function graph(method, path, fields = {}, retries = 3) {
const url = new URL(`${GRAPH}/${path}`);
const init = { method };
const all = { ...fields, access_token: PAGE_TOKEN };
if (method === "GET") {
for (const [key, value] of Object.entries(all)) url.searchParams.set(key, String(value));
} else {
init.headers = { "Content-Type": "application/json" };
init.body = JSON.stringify(all);
}
for (let attempt = 0; ; attempt++) {
const response = await fetch(url, init);
const body = await response.json();
if (!body.error) return body;
if (!RETRY.has(body.error.code) || attempt === retries) throw new GraphError(body.error);
await new Promise((done) => setTimeout(done, waitMs(response, attempt)));
}
}
const post = await graph("POST", `${PAGE_ID}/feed`, { message: "Open until 11pm this Friday." });
const photo = await graph("POST", `${PAGE_ID}/photos`, {
url: "https://example.com/menu.jpg",
caption: "This week's menu",
});
console.log(post.id, photo.post_id);Como se leem e respondem comentários em Python?
Lêem-se os comentários de uma publicação com fields, filter=stream para comentários de todos os níveis por ordem cronológica e order=reverse_chronological para os mais recentes primeiro; depois responde-se como Página, ao enviar uma mensagem para o edge de comentários do próprio comentário. O token tem de vir de alguém que possa executar MODERATE, ou a Meta omite os IDs dos comentários, e responder exige pages_manage_engagement. paging.next leva a comentários mais antigos.
# graph() as in the first example
post_id = post["id"] # {page-id}_{post-id}, as the publish call returned it
page = graph("GET", f"{post_id}/comments", fields="id,message,created_time,can_reply_privately",
filter="stream", order="reverse_chronological", limit=50)
for comment in page["data"]:
if "?" in comment.get("message", ""):
graph("POST", f"{comment['id']}/comments",
message="Thanks for asking! Our hours are on the Page.")
older = page.get("paging", {}).get("next") # follow it to read further backE como se leem e respondem comentários em Node.js?
As mesmas duas chamadas, com o objeto URL a construir a query string: um GET com fields, filter e order e depois um POST para /{comment-id}/comments. can_reply_privately, solicitado em fields, indica se a Página ainda pode enviar uma resposta privada à pessoa que comentou, o que vale a pena saber antes do exemplo de Messenger abaixo. Guarde os IDs dos comentários a que respondeu, para que uma nova execução não responda duas vezes.
// graph() as in the first example
const postId = post.id; // {page-id}_{post-id}, as the publish call returned it
const page = await graph("GET", `${postId}/comments`, {
fields: "id,message,created_time,can_reply_privately",
filter: "stream",
order: "reverse_chronological",
limit: 50,
});
for (const comment of page.data) {
if ((comment.message ?? "").includes("?")) {
await graph("POST", `${comment.id}/comments`, {
message: "Thanks for asking! Our hours are on the Page.",
});
}
}
const older = page.paging?.next; // follow it to read further backComo se envia uma resposta no Messenger em Python?
POST /{page-id}/messages com recipient.id definido como o ID com âmbito de Página da pessoa, vindo do webhook de mensagens, messaging_type RESPONSE e o campo text. O exemplo apanha as duas recusas que não compensa voltar a tentar: erro 10 com subcódigo 2534022 ou 2018278 quando a janela de 24 horas fechou, e 551 quando a pessoa não está disponível. private_reply() coloca recipient.comment_id no lugar do ID, para a única mensagem que um comentário permite dentro de 7 dias.
# graph(), GraphError and PAGE_ID as in the first example
def reply(psid, text):
"""psid: sender.id from the messages webhook, within 24 hours of the person's message."""
try:
return graph("POST", f"{PAGE_ID}/messages", recipient={"id": psid},
messaging_type="RESPONSE", message={"text": text})
except GraphError as e:
if (e.code == 10 and e.subcode in (2534022, 2018278)) or e.code == 551:
return None # the window has closed, or the person is unavailable: no retry
raise
def private_reply(comment_id, text):
"""One Messenger message to the person who commented, within 7 days of the comment."""
return graph("POST", f"{PAGE_ID}/messages", recipient={"comment_id": comment_id},
message={"text": text})Como se envia uma resposta no Messenger em Node.js?
O mesmo corpo de pedido em JavaScript, com recipient, messaging_type e message enviados como JSON pelo graph(). A Meta responde a um envio aceite com recipient_id e message_id, valores que vale a pena guardar junto da conversa. Uma resposta privada leva uma ligação de volta ao comentário a que responde, e a conversa continua na janela normal de 24 horas assim que a pessoa escrever de novo.
// graph(), GraphError and PAGE_ID as in the first example
async function reply(psid, text) {
// psid: sender.id from the messages webhook, within 24 hours of the person's message
try {
return await graph("POST", `${PAGE_ID}/messages`, {
recipient: { id: psid },
messaging_type: "RESPONSE",
message: { text },
});
} catch (e) {
const closed =
e instanceof GraphError && ((e.code === 10 && [2534022, 2018278].includes(e.subcode)) || e.code === 551);
if (closed) return null; // the window has closed, or the person is unavailable: no retry
throw e;
}
}
function privateReply(commentId, text) {
// one Messenger message to the person who commented, within 7 days of the comment
return graph("POST", `${PAGE_ID}/messages`, {
recipient: { comment_id: commentId },
message: { text },
});
}Como se leem as métricas de uma Página em Python?
GET /{page-id}/insights com uma lista de métricas separada por vírgulas, period=day e uma janela since e until em segundos UNIX; um só pedido abrange até 90 dias. Três destas métricas substituíram outras que a Meta retirou: page_media_view substitui page_impressions, page_total_media_view_unique substitui page_impressions_unique e page_follows substitui page_fans, enquanto page_post_engagements conta reações, comentários e partilhas.
# graph() and PAGE_ID as in the first example
until = int(time.time())
since = until - 28 * 86400 # one request can cover up to 90 days
metrics = "page_media_view,page_total_media_view_unique,page_post_engagements,page_follows"
data = graph("GET", f"{PAGE_ID}/insights", metric=metrics, period="day", since=since, until=until)
for metric in data["data"]:
for point in metric["values"]:
print(metric["name"], point["end_time"][:10], point["value"])E como se leem as métricas de uma Página em Node.js?
A mesma chamada, com since e until calculados a partir de Date.now() em segundos. Cada métrica devolve o seu nome, o seu period e uma lista values de pares value e end_time, um por dia; com since definido, o primeiro end_time cai no dia seguinte, para que os dados desse dia fiquem incluídos. O token precisa de read_insights e pages_read_engagement, de alguém com a tarefa ANALYZE.
// graph() and PAGE_ID as in the first example
const until = Math.floor(Date.now() / 1000);
const since = until - 28 * 86400; // one request can cover up to 90 days
const data = await graph("GET", `${PAGE_ID}/insights`, {
metric: "page_media_view,page_total_media_view_unique,page_post_engagements,page_follows",
period: "day",
since,
until,
});
for (const metric of data.data) {
for (const point of metric.values) {
console.log(metric.name, point.end_time.slice(0, 10), point.value);
}
}Como se valida a assinatura de um webhook em Python?
Recalcula-se o X-Hub-Signature-256 a partir do corpo bruto do pedido e do segredo da aplicação, e depois comparam-se os dois em tempo constante. A Meta assina cada POST com um HMAC-SHA256 do payload, com a chave App Secret das definições básicas do painel da aplicação, e escreve-o depois de sha256=. Passe o corpo como bytes, antes de qualquer análise JSON: request.body no Django e await request.body() no FastAPI dão os bytes que a Meta assinou.
import hashlib, hmac, os
APP_SECRET = os.environ["APP_SECRET"].encode() # App Dashboard, Settings, Basic
def signed_by_meta(raw_body: bytes, header: str) -> bool:
"""raw_body: the request body exactly as received. header: X-Hub-Signature-256."""
expected = "sha256=" + hmac.new(APP_SECRET, raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), (header or "").encode())
# Django: signed_by_meta(request.body, request.headers.get("X-Hub-Signature-256"))
# FastAPI: signed_by_meta(await request.body(), request.headers.get("X-Hub-Signature-256"))Como se valida a assinatura de um webhook em Node.js?
A mesma verificação com node:crypto, que precisa do corpo como Buffer: no Express, express.raw mantém-no sem análise nessa rota. timingSafeEqual lança erro com entradas de comprimentos diferentes, por isso o teste de comprimento executa primeiro. Responda 200 depressa e faça o trabalho depois, já que a Meta volta a tentar entregas falhadas e pode enviar um evento duas vezes; a página de verificação trata do handshake hub.challenge que vem antes de qualquer evento.
import crypto from "node:crypto";
const APP_SECRET = process.env.APP_SECRET; // App Dashboard, Settings, Basic
function signedByMeta(rawBody, header = "") {
// rawBody: a Buffer holding the request body exactly as received. header: X-Hub-Signature-256
const digest = crypto.createHmac("sha256", APP_SECRET).update(rawBody).digest("hex");
const expected = Buffer.from(`sha256=${digest}`);
const given = Buffer.from(header);
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}
// Express: app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
// if (!signedByMeta(req.body, req.get("X-Hub-Signature-256"))) return res.sendStatus(401);
// res.sendStatus(200); // then work on JSON.parse(req.body) after answering
// });Que códigos de erro o código deve tratar?
Os que os guias de erros da Meta distinguem, porque cada um exige uma resposta diferente: voltar a tentar um token recusado ou um parâmetro inválido só volta a falhar, enquanto uma chamada limitada tem êxito após uma espera. graph() volta a tentar os códigos temporários e de limite de taxa e lança os restantes para que quem chama trate deles:
Como se executam as mesmas tarefas através da easyCoexistence?
Como ferramentas MCP que o Claude, o ChatGPT ou o seu próprio agente chama numa Página ligada, com o token guardado pela easyCoexistence. Os tokens das Páginas nunca são entregues, pelo que os exemplos acima funcionam com um token da sua própria aplicação Meta; get_social_credentials devolve o ID da Página e a base da Graph API. A ferramenta de cada tarefa:
Erros comuns
- Chamar os endpoints da Página com um token de utilizador. A maioria espera o token próprio da Página, e as chamadas feitas com um token de utilizador ou de aplicação contam para esses limites de taxa em vez dos da Página.
- Publicar duas vezes seguidas o mesmo texto. A Meta recusa publicações consecutivas idênticas com o erro 506, por isso uma tarefa que volte a ser executada tem de variar o conteúdo ou saltar a publicação.
- Somar os visualizadores únicos diários. page_total_media_view_unique conta visualizadores únicos em cada período, por isso os valores diários não somam um mês; peça antes period days_28.
- Enviar o token da Página para um navegador ou uma aplicação. Estas chamadas pertencem a um servidor, onde o token fica fora do alcance de quem consegue ler o cliente.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Preciso de um SDK para chamar a API de Páginas do Facebook?
Não. A Graph API é HTTPS com JSON, por isso bastam pedidos em Python e o fetch integrado no Node.js 18 ou posterior, como mostram os exemplos desta página.
O mesmo código pode publicar em várias Páginas?
Sim. /me/accounts devolve um token separado para cada Página, por isso guarde um por Página e passe o PAGE_ID e o PAGE_TOKEN correspondentes; as chamadas feitas com um token de Página contam para o limite de taxa dessa própria Página.
De onde vem o PSID para uma resposta no Messenger?
Do webhook de mensagens: sender.id em cada evento de mensagens é o ID da pessoa com âmbito de Página, único para essa pessoa e Página. Os IDs de utilizador do Facebook Login têm âmbito de aplicação e não funcionam com a Messenger Platform.
Quanto custa a easyCoexistence para uma Página do Facebook?
Cada Página ligada conta como uma ligação, de US$ 9 a US$ 0.75 por ligação por mês, conforme quantas tiver, e os primeiros 3 dias são gratuitos; as ferramentas MCP estão incluídas.
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