Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

caption

O parâmetro text de uma foto da Página; a referência de fotos da Meta marca message como obsoleto ali.

X-Business-Use-Case-Usage

Cabeçalho de resposta cujo estimated_time_to_regain_access indica os minutos até as chamadas limitadas voltarem a funcionar.

RESPONSE

O messaging_type de uma resposta a uma mensagem que a Página recebeu, enviada dentro da janela de 24 horas.

recipient.comment_id

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:

Publish a post or photoPOST /{page-id}/feed and /{page-id}/photos: pages_manage_posts, CREATE_CONTENT
Read and reply to comments/{post-id}/comments and /{comment-id}/comments: pages_manage_engagement, MODERATE
Reply in MessengerPOST /{page-id}/messages: pages_messaging, MESSAGING
Read insightsGET /{page-id}/insights: read_insights, pages_read_engagement, ANALYZE
Check a webhookX-Hub-Signature-256, with the app secret and no token

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.

Python: graph(), then a post and a photo
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: graph(), then a post and a photo
// 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.

Python: read a post's comments and reply to the questions
# 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

E 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.

Node.js: read a post's comments and reply to the questions
// 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

Como 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.

Python: a Messenger reply and a private reply
# 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.

Node.js: a Messenger reply and a private reply
// 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.

Python: four Page metrics for the last 28 days
# 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.

Node.js: four Page metrics for the last 28 days
// 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.

Python: check X-Hub-Signature-256
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.

Node.js: check X-Hub-Signature-256
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:

190, 102The token was refused, and the subcode says why. A new sign-in is the fix
10, 200 to 299A permission was not granted or was removed. Grant it again
4, 17, 32, 613An app, user or Page rate limit. Stop, wait, then resume gradually
80001Page calls made with a Page token are throttled; the header gives the minutes
368Blocked for policy violations. Wait, and review what was being sent
100An invalid parameter. Fix the request before sending it again
551The person is not available on Messenger. Do not retry
1, 2A temporary issue on Meta's side. Wait and retry

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:

Publishpublish_facebook_post with message, link, image_url or video_url, now or at scheduled_at
Commentslist_social_comments, then reply_to_comment; private set to true sends the one Messenger message
Messengersend_social_dm, with recipient_id set to the sender's ID from the forwarded event
Insightsget_social_insights with metrics and a period, or object_id for one post
Eventsset_social_webhook_destination; each forward carries X-EC-Signature, made with the Page's own secret

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.
Fazer isto com a EasyCoexistence

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