API de Páginas de Facebook en Python y Node.js: ejemplos prácticos
Python y Node.js llaman a la API de Páginas de Facebook con peticiones HTTPS simples a graph.facebook.com/v26.0 usando el token de acceso de la Página: POST /{page-id}/feed y /{page-id}/photos publican, /{post-id}/comments lee y responde comentarios, POST /{page-id}/messages responde en Messenger, GET /{page-id}/insights lee métricas, y un HMAC-SHA256 del cuerpo sin procesar verifica X-Hub-Signature-256 en cada webhook.
easyCoexistence ofrece a una Página conectada estos trabajos como herramientas MCP, desde publish_facebook_post y reply_to_comment hasta send_social_dm y get_social_insights, reenvía sus eventos firmados con X-EC-Signature y entrega a tu propio código el ID de la Página y la base de la API mediante get_social_credentials.
El parámetro text de una foto de Página; la referencia de fotos de Meta marca el campo message como obsoleto ahí.
Cabecera de respuesta cuyo estimated_time_to_regain_access indica los minutos hasta que las llamadas limitadas vuelven a funcionar.
El messaging_type de una respuesta a un mensaje que recibió la Página, enviado dentro de la ventana de atención de 24 horas.
Cómo una respuesta privada se dirige a la persona que comentó, a través del mismo endpoint /{page-id}/messages.
¿Qué necesitan los ejemplos antes de ejecutarse?
Un ID de Página y el token de acceso de esa Página, leído desde /me/accounts con un token de usuario de larga duración, además de Python 3 con requests, o Node.js 18 o posterior, cuyo fetch integrado no necesita paquete. Cada trabajo también necesita su permiso en el token y su tarea en la Página, y los ejemplos llaman a la API Graph v26.0:
¿Cómo se publica una publicación y una foto en Python?
Con un único helper que reutilizan los ejemplos posteriores: graph() añade el token de la Página, envía los parámetros GET en la cadena de consulta y los campos POST como JSON, igual que los ejemplos oficiales de Meta, y convierte el objeto de error de Meta en un GraphError con code y error_subcode. Espera y reintenta solo los códigos temporales y de límite de tasa, durante el tiempo que indique X-Business-Use-Case-Usage cuando llega esa cabecera, y lanza el resto de inmediato.
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"])¿Cómo se publican en Node.js?
Con el mismo helper en Node.js 18 o posterior, guardado como archivo .mjs para que funcione el await de nivel superior, y con el fetch integrado en lugar de una librería cliente. La llamada de foto envía url y caption, el campo text del edge photos; Meta responde con el id de la foto y el post_id de la publicación de la Página que contiene la foto, mientras que la llamada al feed responde solo con el id de la publicación.
// 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);¿Cómo se leen y responden comentarios en Python?
Lee los comentarios de una publicación con fields, filter=stream para comentarios de todos los niveles en orden cronológico y order=reverse_chronological para los más nuevos primero, y luego responde como la Página publicando un mensaje en el edge de comentarios del propio comentario. El token debe venir de alguien que pueda realizar MODERATE, o Meta omite los ID de comentario, y responder requiere pages_manage_engagement. paging.next lleva a comentarios más antiguos.
# 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 back¿Cómo se leen y responden comentarios en Node.js?
Las mismas dos llamadas, con el objeto URL construyendo la cadena de consulta: un GET con fields, filter y order, y después un POST a /{comment-id}/comments. can_reply_privately, solicitado en fields, indica si la Página todavía puede enviar a ese comentarista una respuesta privada, algo útil de saber antes del ejemplo de Messenger más abajo. Guarda los ID de los comentarios a los que respondes, para que una nueva ejecución no responda dos veces.
// 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 back¿Cómo se envía una respuesta de Messenger en Python?
POST /{page-id}/messages con recipient.id igual al ID con alcance de Página de la persona, obtenido del webhook de mensajes, messaging_type RESPONSE y el text. El ejemplo captura los dos rechazos que no vale la pena reintentar: error 10 con subcode 2534022 o 2018278 cuando la ventana de atención de 24 horas se ha cerrado, y 551 cuando la persona no está disponible. private_reply() pone recipient.comment_id en lugar del ID, para el único mensaje que permite un comentario dentro de 7 días.
# 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})¿Cómo se envía una respuesta de Messenger en Node.js?
El mismo cuerpo de la petición en JavaScript, con recipient, messaging_type y message enviados como JSON mediante graph(). Meta responde a un envío aceptado con recipient_id y message_id, que conviene guardar junto a la conversación. Una respuesta privada lleva un enlace al comentario al que responde, y la conversación continúa en la ventana de atención estándar de 24 horas cuando la persona vuelve a escribir.
// 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 },
});
}¿Cómo se leen las métricas de la Página en Python?
GET /{page-id}/insights con una lista de métricas separadas por comas, period=day y una ventana since y until en segundos UNIX; una sola petición cubre hasta 90 días. Tres de estas métricas sustituyeron a otras que Meta retiró: page_media_view reemplaza a page_impressions, page_total_media_view_unique a page_impressions_unique y page_follows a page_fans, mientras que page_post_engagements cuenta reacciones, comentarios y compartidos.
# 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"])¿Cómo se leen las métricas de la Página en Node.js?
La misma llamada, con since y until calculados a partir de Date.now() en segundos. Cada métrica devuelve su nombre, su period y una lista values de pares value y end_time, uno por día; con since definido, el primer end_time cae en el día siguiente, de modo que se incluye el dato de ese día. El token necesita read_insights y pages_read_engagement, de alguien con la tarea 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);
}
}¿Cómo se verifica la firma de un webhook en Python?
Recalcula X-Hub-Signature-256 a partir del cuerpo sin procesar de la petición y del App Secret de la aplicación, y compara ambos valores en tiempo constante. Meta firma cada POST con un HMAC-SHA256 de la carga útil, con la clave App Secret de los ajustes básicos del App Dashboard, y lo escribe tras sha256=. Pasa el cuerpo como bytes, antes de cualquier análisis de JSON: request.body en Django y await request.body() en FastAPI devuelven los bytes que firmó Meta.
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"))¿Cómo se verifica la firma de un webhook en Node.js?
La misma comprobación con node:crypto, que necesita el cuerpo como Buffer: en Express, express.raw lo mantiene sin analizar en esa ruta. timingSafeEqual lanza un error con entradas de distinta longitud, por eso la prueba de longitud se ejecuta primero. Responde 200 rápidamente y haz el trabajo después, ya que Meta reintenta las entregas fallidas y puede enviar un evento dos veces; la página de verificación cubre el handshake hub.challenge que ocurre antes de cualquier 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
// });¿Qué códigos de error debe tratar el código?
Los que distinguen las guías de errores de Meta, porque cada uno exige una respuesta distinta: reintentar un token rechazado o un parámetro incorrecto solo vuelve a fallar, mientras que una llamada limitada tiene éxito tras una espera. graph() reintenta los códigos temporales y de límite de tasa y lanza los demás para que los gestione quien llama:
¿Cómo ejecutar los mismos trabajos a través de easyCoexistence?
Como herramientas MCP que Claude, ChatGPT o tu propio agente llama sobre una Página conectada, con el token guardado en easyCoexistence. Los tokens de Página nunca se entregan, así que los ejemplos anteriores funcionan con un token de tu propia app de Meta; get_social_credentials devuelve el ID de la Página y la base de la API Graph. La herramienta de cada trabajo:
Errores comunes
- Llamar a los endpoints de Página con un token de usuario. La mayoría espera el token propio de la Página, y las llamadas hechas con un token de usuario o de aplicación cuentan contra esos límites de tasa en lugar de los de la Página.
- Publicar el mismo texto dos veces seguidas. Meta rechaza publicaciones duplicadas consecutivas con el error 506, así que un trabajo que se vuelve a ejecutar tiene que variar el contenido u omitir la publicación.
- Sumar los espectadores únicos diarios. page_total_media_view_unique cuenta espectadores únicos en cada periodo, así que los valores diarios no suman un mes; pide en su lugar period days_28.
- Enviar el token de la Página a un navegador o a una app. Estas llamadas deben hacerse en un servidor, donde el token queda fuera del alcance de cualquiera que pueda leer el cliente.
De US$ 9 a US$ 0.75 por conexión al mes, que baja a medida que añades conexiones, y los primeros 3 días son gratis.
Preguntas frecuentes
¿Necesito un SDK para llamar a la API de Páginas de Facebook?
No. La API Graph es HTTPS con JSON, así que bastan las peticiones en Python y el fetch integrado en Node.js 18 o posterior, como muestran los ejemplos de esta página.
¿El mismo código puede publicar en varias Páginas?
Sí. /me/accounts devuelve un token distinto para cada Página, así que guarda uno por Página y pasa el PAGE_ID y PAGE_TOKEN correspondientes; las llamadas hechas con un token de Página cuentan contra el límite de tasa de esa Página.
¿De dónde sale el PSID para una respuesta de Messenger?
Del webhook de mensajes: sender.id en cada evento de messaging es el ID con alcance de Página de la persona, único para esa persona y esa Página. Los ID de usuario de Facebook Login tienen alcance de aplicación y no funcionan con Messenger Platform.
¿Cuánto cuesta easyCoexistence para una Página de Facebook?
Cada Página conectada cuenta como una conexión, a un precio de US$ 9 a US$ 0.75 por conexión al mes según cuántas tengas, y los primeros 3 días son gratis; las herramientas MCP están incluidas.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el