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 requisições 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 comentários, POST /{page-id}/messages responde no Messenger, GET /{page-id}/insights lê métricas, e um HMAC-SHA256 do corpo bruto verifica o X-Hub-Signature-256 de cada webhook.
O easyCoexistence oferece a uma Página conectada essas tarefas como ferramentas MCP, de publish_facebook_post e reply_to_comment até send_social_dm e get_social_insights, repassa seus eventos assinados com X-EC-Signature e entrega ao seu código o ID da Página e a base da API por meio de get_social_credentials.
O parâmetro text de uma foto da Página; a referência de fotos da Meta marca message como descontinuado ali.
Cabeçalho de resposta cujo estimated_time_to_regain_access informa os minutos até que as chamadas limitadas voltem 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, pelo mesmo endpoint /{page-id}/messages.
O que os exemplos precisam antes de rodar?
Um ID da Página e o token de acesso dessa Página, lido de /me/accounts com um token de usuário de longa duração, além de Python 3 com requests, ou Node.js 18 ou posterior, cujo fetch embutido não precisa de pacote. Cada tarefa também precisa da sua permissão no token e da sua tarefa na Página, e os exemplos chamam a Graph API v26.0:
Como publicar um post e uma foto em Python?
Com um auxiliar que os exemplos seguintes reutilizam: graph() adiciona o token da Página, envia parâmetros GET na query string e campos POST como JSON, como os exemplos da própria Meta, e transforma o objeto de erro da Meta em um GraphError com code e error_subcode. Ele espera e repete apenas os códigos temporários e de limite de taxa, pelo tempo que X-Business-Use-Case-Usage indicar quando esse cabeçalho voltar, e lança os demais imediatamente.
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"])E como publicar em Node.js?
Com o mesmo auxiliar em Node.js 18 ou posterior, salvo como arquivo .mjs para que o top-level await funcione, e com o fetch embutido 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 do post da Página que contém a foto, enquanto a chamada do feed responde apenas com o id do post.
// 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 ler e responder comentários em Python?
Leia os comentários de um post com fields, filter=stream para comentários de todos os níveis em ordem cronológica e order=reverse_chronological para os mais recentes primeiro, depois responda como a Página publicando uma mensagem no edge de comentários do próprio comentário. O token precisa vir de alguém que possa executar MODERATE, ou a Meta deixa os IDs dos comentários de fora, e responder exige pages_manage_engagement. paging.next leva a itens 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 backComo ler e responder comentários em Node.js?
As mesmas duas chamadas, com o objeto URL montando a query string: um GET com fields, filter e order, depois um POST para /{comment-id}/comments. can_reply_privately, pedido em fields, indica se a Página ainda pode enviar ao comentarista uma resposta privada, o que vale saber antes do exemplo de Messenger abaixo. Guarde os IDs dos comentários que você 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 enviar uma resposta no Messenger em Python?
POST /{page-id}/messages com recipient.id definido como o ID da pessoa com escopo de Página, vindo do webhook de mensagens, messaging_type RESPONSE e o text. O exemplo captura as duas recusas que não valem repetição: erro 10 com subcode 2534022 ou 2018278 quando a janela de 24 horas já 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})E como enviar uma resposta no Messenger em Node.js?
O mesmo corpo de requisição em JavaScript, com recipient, messaging_type e message enviados como JSON pelo graph(). A Meta responde a um envio aceito com recipient_id e message_id, que vale guardar junto da conversa. Uma resposta privada carrega um vínculo de volta ao comentário que ela responde, e a conversa segue na janela padrão de 24 horas quando a pessoa responde.
// 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 ler os insights 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; uma requisição cobre até 90 dias. Três dessas métricas substituíram outras que a Meta descontinuou: page_media_view no lugar de page_impressions, page_total_media_view_unique no lugar de page_impressions_unique e page_follows no lugar de page_fans, enquanto page_post_engagements conta reações, comentários e compartilhamentos.
# 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 ler os insights 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 volta com seu nome, 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 a ele, de modo que os dados desse dia são 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 verificar a assinatura de um webhook em Python?
Recalcule X-Hub-Signature-256 a partir do corpo bruto da requisição e do app secret, depois compare os dois em tempo constante. A Meta assina cada POST com um HMAC-SHA256 do payload, usando como chave o App Secret das configurações básicas do App Dashboard, e grava o resultado depois de sha256=. Passe o corpo como bytes, antes de qualquer parsing de JSON: request.body no Django e await request.body() no FastAPI entregam 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 verificar 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 o corpo sem parsing naquela rota. timingSafeEqual lança erro com entradas de tamanhos diferentes, então o teste de tamanho roda primeiro. Responda 200 rapidamente e faça o trabalho depois, pois a Meta repete entregas que falharam e pode enviar um evento duas vezes; a página de verificação cobre o 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
// });Quais códigos de erro o código deve tratar?
Os que os guias de erro da Meta distinguem, porque cada um exige uma resposta diferente: repetir uma requisição com token recusado ou parâmetro inválido só falha de novo, enquanto uma chamada limitada tem sucesso depois de uma espera. graph() repete os códigos temporários e de limite de taxa e lança os outros para quem chamou tratar:
Como executar as mesmas tarefas pelo easyCoexistence?
Como ferramentas MCP que Claude, ChatGPT ou seu próprio agente chamam em uma Página conectada, com o token mantido pelo easyCoexistence. Os tokens da Página nunca são entregues, então os exemplos acima rodam com um token do seu próprio app da Meta; get_social_credentials devolve o ID da Página e a base da Graph API. A ferramenta de cada tarefa:
Erros comuns
- Chamar endpoints da Página com um token de usuário. A maioria espera o token próprio da Página, e chamadas feitas com token de usuário ou de app contam nos limites de taxa deles, e não nos da Página.
- Publicar o mesmo texto duas vezes seguidas. A Meta recusa posts duplicados consecutivos com erro 506, então uma tarefa que roda de novo precisa variar o conteúdo ou pular o post.
- Somar visualizadores únicos diários. page_total_media_view_unique conta visualizadores únicos em cada período, então os valores diários não somam um mês; peça period days_28 no lugar.
- Enviar o token da Página para um navegador ou app. Essas chamadas pertencem a um servidor, onde o token fica fora do alcance de quem pode ler o cliente.
De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os 3 primeiros 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 de um SDK para chamar a API de Páginas do Facebook?
Não. A Graph API é HTTPS com JSON, então requisições em Python e o fetch embutido no Node.js 18 ou posterior bastam, 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, então guarde um por Página e passe o PAGE_ID e o PAGE_TOKEN correspondentes; chamadas feitas com token de Página contam no limite de taxa próprio dessa Página.
De onde vem o PSID de uma resposta no Messenger?
Do webhook de mensagens: sender.id em cada evento de mensagem é o ID da pessoa com escopo de Página, único para essa pessoa e Página. IDs de usuário do Facebook Login têm escopo de app e não funcionam com a Messenger Platform.
Quanto custa o easyCoexistence para uma Página do Facebook?
Cada Página conectada conta como uma conexão, de US$ 9 a US$ 0.75 por conexão por mês conforme a quantidade que você tem, e os 3 primeiros dias são grátis; as ferramentas MCP vêm incluídas.
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