Facebook Pages API in Python e Node.js: esempi funzionanti
Python e Node.js chiamano la Facebook Pages API con semplici richieste HTTPS verso graph.facebook.com/v26.0, usando il token di accesso della Pagina: POST /{page-id}/feed e /{page-id}/photos pubblicano, /{post-id}/comments legge e risponde ai commenti, POST /{page-id}/messages risponde su Messenger, GET /{page-id}/insights legge le metriche, e un HMAC-SHA256 del corpo grezzo verifica X-Hub-Signature-256 su ogni webhook.
easyCoexistence offre a una Pagina collegata queste operazioni come strumenti MCP, da publish_facebook_post e reply_to_comment fino a send_social_dm e get_social_insights, inoltra i suoi eventi firmati con X-EC-Signature e consegna al tuo codice l'ID della Pagina e la base API tramite get_social_credentials.
Il parametro text di una foto della Pagina: il riferimento alle foto di Meta indica come deprecato il messaggio in quel punto.
Intestazione di risposta il cui estimated_time_to_regain_access indica i minuti prima che le chiamate limitate tornino a funzionare.
Il messaging_type per una risposta a un messaggio ricevuto dalla Pagina, inviata entro la finestra di 24 ore.
Come una risposta privata indirizza la persona che ha commentato, attraverso lo stesso endpoint /{page-id}/messages.
Di cosa hanno bisogno gli esempi prima di essere eseguiti?
Un ID della Pagina e il token di accesso di quella Pagina, letto da /me/accounts con un token utente di lunga durata, più Python 3 con requests, oppure Node.js 18 o successivo, il cui fetch integrato non richiede alcun pacchetto. Ogni operazione richiede anche il relativo permesso sul token e la relativa attività sulla Pagina, e gli esempi chiamano Graph API v26.0:
Come si pubblicano un post e una foto in Python?
Con un unico helper che gli esempi successivi riusano: graph() aggiunge il token della Pagina, invia i parametri GET nella query string e i campi POST come JSON, come fanno gli esempi di Meta, e trasforma l'oggetto errore di Meta in un GraphError che porta code e error_subcode. Attende e riprova solo i codici temporanei e quelli di limite di frequenza, per il tempo che X-Business-Use-Case-Usage indica quando arriva quell'intestazione, e solleva subito tutti gli altri.
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"])Come si pubblicano in Node.js?
Con lo stesso helper in Node.js 18 o successivo, salvato come file .mjs così che top-level await funzioni, e con il fetch integrato al posto di una libreria client. La chiamata per la foto invia url e caption, il campo text dell'edge photos; Meta risponde con l'id della foto e il post_id del post della Pagina che contiene la foto, mentre la chiamata al feed risponde con il solo id del 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);Come si leggono e si rispondono i commenti in Python?
Si leggono i commenti di un post con fields, filter=stream per i commenti a tutti i livelli in ordine cronologico e order=reverse_chronological per i più recenti per primi, poi si risponde come Pagina inviando un messaggio all'edge commenti del commento stesso. Il token deve provenire da qualcuno che può eseguire MODERATE, altrimenti Meta omette gli ID dei commenti, e rispondere richiede pages_manage_engagement. paging.next porta più indietro nel tempo.
# 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 backCome si leggono e si rispondono i commenti in Node.js?
Le stesse due chiamate, con l'oggetto URL che costruisce la query string: una GET con fields, filter e order, poi una POST a /{comment-id}/comments. can_reply_privately, richiesto in fields, indica se la Pagina può ancora inviare a quel commentatore una risposta privata, cosa utile da sapere prima dell'esempio di Messenger qui sotto. Conserva gli ID dei commenti a cui rispondi, così che una nuova esecuzione non risponda due volte.
// 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 backCome si invia una risposta su Messenger in Python?
POST /{page-id}/messages con recipient.id impostato sull'ID con ambito Pagina della persona, preso dal webhook dei messaggi, messaging_type RESPONSE e il testo. L'esempio intercetta i due rifiuti che non vale la pena riprovare: errore 10 con sottocodice 2534022 o 2018278 quando la finestra di 24 ore è chiusa, e 551 quando la persona non è disponibile. private_reply() mette recipient.comment_id al posto dell'ID, per l'unico messaggio che un commento consente entro 7 giorni.
# 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})Come si invia una risposta su Messenger in Node.js?
Lo stesso corpo della richiesta in JavaScript, con recipient, messaging_type e message inviati come JSON da graph(). Meta risponde a un invio accettato con recipient_id e message_id, che conviene salvare insieme alla conversazione. Una risposta privata contiene un collegamento al commento a cui risponde, e la conversazione prosegue nella finestra standard di 24 ore quando la persona scrive di nuovo.
// 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 },
});
}Come si leggono gli insight di una Pagina in Python?
GET /{page-id}/insights con un elenco di metriche separate da virgola, period=day e una finestra since e until in secondi UNIX; una sola richiesta copre fino a 90 giorni. Tre di queste metriche sostituiscono quelle che Meta ha ritirato: page_media_view al posto di page_impressions, page_total_media_view_unique al posto di page_impressions_unique e page_follows al posto di page_fans, mentre page_post_engagements conta reazioni, commenti e condivisioni.
# 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"])Come si leggono gli insight di una Pagina in Node.js?
La stessa chiamata, con since e until calcolati da Date.now() in secondi. Ogni metrica torna con il suo nome, il suo period e una lista values di coppie value ed end_time, una per giorno; con since impostato, il primo end_time cade il giorno dopo, così che i dati di quel giorno sono inclusi. Il token richiede read_insights e pages_read_engagement, da parte di qualcuno con l'attività 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);
}
}Come si verifica la firma di un webhook in Python?
Si ricalcola X-Hub-Signature-256 dal corpo grezzo della richiesta e dall'App Secret, poi si confrontano i due valori a tempo costante. Meta firma ogni POST con un HMAC-SHA256 del payload, con chiave l'App Secret presente nelle impostazioni di base della App Dashboard, e lo scrive dopo sha256=. Passa il corpo come byte, prima di qualsiasi parsing JSON: request.body in Django e await request.body() in FastAPI danno entrambi i byte che Meta ha firmato.
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"))Come si verifica la firma di un webhook in Node.js?
Lo stesso controllo con node:crypto, che richiede il corpo come Buffer: in Express, express.raw lo mantiene non elaborato su quella route. timingSafeEqual genera un errore con input di lunghezza diversa, quindi il controllo sulla lunghezza va eseguito per primo. Rispondi 200 rapidamente e svolgi il lavoro dopo, perché Meta riprova le consegne fallite e può inviare un evento due volte; la pagina di verifica copre l'handshake hub.challenge che precede qualsiasi 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
// });Quali codici di errore deve gestire il codice?
Quelli che le guide agli errori di Meta distinguono, perché ciascuno richiede una risposta diversa: riprovare un token rifiutato o un parametro errato fallisce di nuovo, mentre una chiamata limitata riesce dopo un'attesa. graph() riprova i codici temporanei e quelli di limite di frequenza e solleva gli altri perché il chiamante li gestisca:
Come si eseguono le stesse operazioni tramite easyCoexistence?
Come strumenti MCP che Claude, ChatGPT o il tuo agente chiama su una Pagina collegata, con il token custodito da easyCoexistence. I token delle Pagine non vengono mai consegnati, quindi gli esempi sopra funzionano con un token della tua app Meta; get_social_credentials restituisce l'ID della Pagina e la base di Graph API. Lo strumento di ogni operazione:
Errori comuni
- Chiamare gli endpoint della Pagina con un token utente. La maggior parte si aspetta il token proprio della Pagina, e le chiamate fatte con un token utente o app contano sui limiti di frequenza di quelli invece che su quelli della Pagina.
- Pubblicare lo stesso testo due volte di seguito. Meta rifiuta i post duplicati consecutivi con errore 506, quindi un'operazione che viene rieseguita deve variare il contenuto o saltare il post.
- Sommare i visitatori unici giornalieri. page_total_media_view_unique conta i visitatori unici in ciascun periodo, quindi i valori giornalieri non si sommano a un mese; richiedi invece period days_28.
- Inviare il token della Pagina a un browser o a un'app. Queste chiamate vanno fatte sul server, dove il token resta fuori dalla portata di chiunque possa leggere il client.
Da US$ 9 a US$ 0,75 per connessione al mese, con un calo man mano che aggiungi connessioni, e i primi 3 giorni sono gratuiti.
Domande frequenti
Serve un SDK per chiamare la Facebook Pages API?
No. La Graph API è HTTPS con JSON, quindi bastano le richieste in Python e il fetch integrato in Node.js 18 o successivo, come mostrano gli esempi di questa pagina.
Lo stesso codice può pubblicare su più Pagine?
Sì. /me/accounts restituisce un token separato per ogni Pagina, quindi conservane uno per Pagina e passa il PAGE_ID e il PAGE_TOKEN corrispondenti; le chiamate fatte con un token di Pagina contano sul limite di frequenza di quella Pagina.
Da dove arriva il PSID per una risposta su Messenger?
Dal webhook dei messaggi: sender.id in ogni evento di messaggistica è l'ID con ambito Pagina della persona, unico per quella persona e quella Pagina. Gli ID utente di Facebook Login sono con ambito app e non funzionano con la Messenger Platform.
Quanto costa easyCoexistence per una Pagina Facebook?
Ogni Pagina collegata conta come una connessione, da US$ 9 a US$ 0,75 per connessione al mese a seconda di quante ne hai, e i primi 3 giorni sono gratuiti; gli strumenti MCP sono inclusi.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il