EntrarComeçar teste grátis
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 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.

caption

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

X-Business-Use-Case-Usage

Cabeçalho de resposta cujo estimated_time_to_regain_access informa os minutos até que as chamadas limitadas voltem 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, 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:

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

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"])

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

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

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

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

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})

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.

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

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

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

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

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
// });

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:

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 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:

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 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.
Fazendo isso com o EasyCoexistence

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