Como Usar a Graph API
do Meta para Automações
A Graph API é a chave que conecta qualquer sistema externo ao ecossistema Meta — Facebook, Instagram e Messenger. Neste guia você vai do conceito básico às chamadas reais de API, com exemplos práticos para publicar posts, buscar leads, acessar insights de anúncios e integrar com n8n e Make.com.
A Graph API do Meta é a interface que permite automatizar ações no Facebook e Instagram — publicar posts, buscar leads de formulários, acessar métricas de anúncios, gerenciar comentários e muito mais. A versão atual é a v25.0 (fevereiro de 2026). A URL base é https://graph.facebook.com/v25.0/. Para usar, você precisa de um App ID + Token de acesso. Para automações em produção, o System User Token (não expira, gerado no Business Manager) é o mais indicado.
- O que é a Graph API do Meta
- Como funciona: nós, arestas e campos
- Versão atual e versionamento
- Autenticação: tokens e permissões
- Explorador da Graph API: seu laboratório
- Endpoint 1 — Publicar post em Página
- Endpoint 2 — Buscar leads de formulários
- Endpoint 3 — Insights de anúncios
- Endpoint 4 — Publicar no Instagram
- Endpoint 5 — Webhooks em tempo real
- Integrar com n8n e Make.com
- Limites de taxa e boas práticas
- Erros comuns e como resolver
- Recursos da Expert Digital
- FAQ — perguntas frequentes
O que é a Graph API do Meta
A Graph API é a principal interface de programação (API) do Meta para ler e escrever dados no ecossistema Facebook e Instagram de forma programática. É chamada de "Graph" porque os dados são organizados como um grafo — uma estrutura de nós (pessoas, páginas, posts, anúncios, comentários) conectados por arestas (relacionamentos: a Página tem posts, o post tem comentários).
Em termos práticos: tudo que você faz manualmente no Facebook e no Instagram — publicar, ler comentários, verificar métricas, buscar leads — pode ser feito via Graph API de forma automática, integrada a qualquer sistema externo.
Como funciona: nós, arestas e campos
Toda chamada à Graph API segue a mesma lógica de URL:
https://graph.facebook.com/v25.0/{nó}/{aresta}?fields=campo1,campo2&access_token=SEU_TOKEN
# Exemplos:
# Buscar info de uma Página:
GET https://graph.facebook.com/v25.0/me?fields=id,name,fan_count
# Buscar posts da Página:
GET https://graph.facebook.com/v25.0/{page-id}/feed?fields=id,message,created_time
# Publicar um post:
POST https://graph.facebook.com/v25.0/{page-id}/feed
message="Novo post publicado via API!"
?fields=campo1,campo2. Requisições sem fields retornam apenas id e name. Selecionar apenas os campos necessários reduz o tamanho da resposta e aumenta a velocidade.
Versão atual e versionamento
A Graph API é versionada — a Meta lança novas versões aproximadamente a cada 6 meses e mantém cada versão disponível por 2 anos. Usar versões antigas é arriscado porque elas são descontinuadas sem aviso.
| Versão | Status | Lançamento | Descontinuação |
|---|---|---|---|
| v25.0 | Atual — use esta | Fev 2026 | ~Fev 2028 |
| v24.0 | Suportada | Out 2025 | ~Out 2027 |
| v23.0 | Suportada | Mai 2025 | ~Mai 2027 |
| v20.0 | Fim set/2026 | Mai 2024 | Set 2026 |
| v19.0 | Fim mai/2026 | Jan 2024 | Mai 2026 |
/v19.0/ e /v20.0/ por /v25.0/ nos seus workflows do n8n e Make.com para evitar quebras.
Autenticação: tokens de acesso e permissões
A Graph API usa tokens OAuth 2.0. Para automações em produção, existem 3 tipos principais:
| Tipo de Token | Validade | Como obter | Melhor para |
|---|---|---|---|
| User Token (curto) | ~1 hora | Explorador da Graph API ou OAuth flow | Testes rápidos apenas |
| User Token (longo) | 60 dias | Endpoint /oauth/access_token |
Integrações simples |
| Page Access Token | Não expira* | Endpoint /{user-id}/accounts |
Automações de Página |
| System User Token | Não expira | Business Manager → Usuários do Sistema | Produção — recomendado |
| App Token | Até Secret mudar | app-id|app-secret |
Validação de webhooks |
*Page Access Token não expira quando gerado a partir de um User Token de longa duração.
Fluxo completo para obter um Page Token permanente
GET https://graph.facebook.com/v25.0/oauth/access_token?
grant_type=fb_exchange_token&
client_id=SEU_APP_ID&
client_secret=SEU_APP_SECRET&
fb_exchange_token=TOKEN_CURTO_DO_EXPLORADOR
# Resposta:
{
"access_token": "EAABs...", // token de 60 dias
"token_type": "bearer",
"expires_in": 5183944 // ~60 dias em segundos
}
GET https://graph.facebook.com/v25.0/me/accounts?
access_token=TOKEN_60_DIAS
# Resposta (array de Páginas que você administra):
{
"data": [{
"id": "123456789",
"name": "Nome da Sua Página",
"access_token": "EAACs..." // Page Token — NÃO expira
}]
}
business.facebook.com → Configurações → Usuários do Sistema. Ele nunca expira, não depende de nenhum usuário humano logar e sobrevive mesmo se você sair da empresa.
Explorador da Graph API: seu laboratório
Antes de colocar qualquer chamada em produção, teste no Explorador da Graph API — a ferramenta oficial de testes da Meta:
- → Acesse
developers.facebook.com/tools/explorer/ - → Selecione seu App no dropdown superior direito
- → Clique em "Generate Access Token" e selecione as permissões necessárias
- → Use o campo de busca para montar a URL do endpoint e testar a resposta em JSON
- → Clique em "Code" no canto superior para ver o código equivalente em Python, JavaScript, PHP ou cURL
- → Use o botão "Debug Token" para verificar quando o token expira e quais permissões ele tem
Uma das automações mais usadas em marketing digital: publicar posts em Páginas do Facebook via Graph API, integrado ao n8n ou Make.com para agendamento e criação em escala.
POST https://graph.facebook.com/v25.0/{page-id}/feed
# Body (form-data ou JSON):
{
"message": "Novo conteúdo publicado via API! 🚀 #marketing #automação",
"access_token": PAGE_ACCESS_TOKEN
}
# Resposta:
{ "id": "123456789_987654321" } // ID do post criado
POST https://graph.facebook.com/v25.0/{page-id}/feed
{
"message": "Veja nosso novo artigo 👇",
"link": "https://expertdigitaloficial.com.br/blog/o-que-e-llm",
"access_token": PAGE_ACCESS_TOKEN
}
# O Facebook faz scraping do Open Graph do link automaticamente
POST https://graph.facebook.com/v25.0/{page-id}/feed
{
"message": "Post agendado para amanhã às 9h!",
"scheduled_publish_time": 1748512800, // timestamp Unix da data
"published": false,
"access_token": PAGE_ACCESS_TOKEN
}
A Graph API permite acessar todos os leads coletados nos formulários de Lead Ads — sem precisar fazer download manual do CSV no painel. Com Webhook, você recebe cada lead assim que ele preenche o formulário.
GET https://graph.facebook.com/v25.0/{form-id}/leads?
fields=id,created_time,field_data&
access_token=PAGE_ACCESS_TOKEN
# Resposta:
{
"data": [{
"id": "1234567890",
"created_time": "2026-05-05T14:22:00+0000",
"field_data": [
{ "name": "full_name", "values": ["João Silva"] },
{ "name": "email", "values": ["joao@email.com"] },
{ "name": "phone_number","values": ["11999999999"] }
]
}]
}
GET https://graph.facebook.com/v25.0/{form-id}/leads?
fields=id,created_time,field_data&
filtering=[{"field":"time_created","operator":"GREATER_THAN","value":1748476800}]&
access_token=PAGE_ACCESS_TOKEN
leadgen no painel do seu app (Meta Developers → Webhooks). Cada novo lead é enviado ao seu endpoint em segundos — sem polling, sem custo de chamadas desnecessárias.
A Marketing API (parte da Graph API) permite extrair métricas de performance de anúncios programaticamente — sem abrir o Gerenciador de Anúncios. Isso possibilita criar dashboards automáticos no Google Sheets, Looker Studio ou Power BI.
GET https://graph.facebook.com/v25.0/act_{ad-account-id}/insights?
fields=campaign_name,impressions,clicks,spend,ctr,cpc,cpm,reach,
actions,cost_per_action_type&
date_preset=last_7d&
level=campaign&
access_token=SYSTEM_USER_TOKEN
# Nota: ad-account-id começa com "act_" — ex: act_123456789
GET https://graph.facebook.com/v25.0/act_{ad-account-id}/insights?
fields=campaign_name,spend,impressions,reach,actions&
time_range={"since":"2026-04-01","until":"2026-04-30"}&
time_increment=1& // 1 = por dia; 7 = por semana
level=campaign&
access_token=SYSTEM_USER_TOKEN
reach e impressions no nível de post e página são descontinuados e substituídos por media_views e media_viewers. Atualize seus workflows que dependem dessas métricas antes do prazo.
A publicação no Instagram via Graph API segue um processo de dois passos: primeiro cria-se um container de mídia (envia a imagem/vídeo), depois publica-se o container. Funciona apenas para contas Business e Creator.
POST https://graph.facebook.com/v25.0/{ig-user-id}/media
{
"image_url": "https://sua-cdn.com/imagem.jpg", // URL pública acessível
"caption": "Nova publicação via API! 🚀 #marketing",
"access_token": PAGE_ACCESS_TOKEN
}
# Resposta:
{ "id": "17896129349500001" } // creation_id para o próximo passo
POST https://graph.facebook.com/v25.0/{ig-user-id}/media_publish
{
"creation_id": "17896129349500001", // ID do Passo 1
"access_token": PAGE_ACCESS_TOKEN
}
# Resposta:
{ "id": "17841405822304914" } // ID do post publicado no Instagram
/{creation-id}?fields=status_code e aguarde o retorno FINISHED antes de chamar /media_publish. Tentar publicar enquanto o vídeo ainda processa retorna erro.
Webhooks invertem o fluxo: em vez de você consultar a API periodicamente (polling), o Meta empurra os dados para o seu sistema assim que algo acontece — um novo lead, um novo comentário, uma mudança na Página. É mais eficiente e mais rápido.
Configurar Webhook no Meta Developers
- 1 No painel do app, acesse Webhooks no menu lateral
- 2 Clique em "Adicionar assinatura de produto" e selecione o objeto:
page,leadgen,instagram - 3 Configure Callback URL — o endpoint do seu sistema (n8n Webhook URL, Make.com URL)
- 4 Configure o Verify Token — uma string secreta para confirmar que você é o destinatário legítimo
- 5 Selecione os campos de assinatura: para leads, marque
leadgen; para posts, marquefeed - 6 Clique em Verificar e Salvar — o Meta faz um GET no seu endpoint com
hub.challengepara verificar
{
"object": "page",
"entry": [{
"id": "123456789", // ID da Página
"time": 1748476800,
"changes": [{
"value": {
"leadgen_id": "987654321", // ID do lead
"form_id": "111222333", // ID do formulário
"page_id": "123456789",
"adgroup_id": "444555666",
"ad_id": "777888999"
},
"field": "leadgen"
}]
}]
}
Após receber o Webhook, use o leadgen_id para buscar os dados completos do lead via GET na Graph API:
GET https://graph.facebook.com/v25.0/{leadgen_id}?
fields=id,created_time,field_data&
access_token=PAGE_ACCESS_TOKEN
Integrar com n8n e Make.com
n8n — nó Facebook Graph API
Adicione o nó "Facebook Graph API" e configure com suas credenciais. Use Method, URL e Body para montar qualquer chamada. Para leads, use o nó "Facebook Lead Ads Trigger" que configura o Webhook automaticamente.
Nó nativo disponívelMake.com — módulo Graph API
Use o módulo "Facebook → Make an API Call" para chamadas personalizadas. O Make tem módulos nativos para Facebook Pages e Instagram, reduzindo a necessidade de configurar chamadas manuais na maioria dos casos.
Módulos nativos disponíveisHTTP Request genérico
Para endpoints não cobertos pelos nós nativos, use o nó "HTTP Request" (n8n) ou o módulo "HTTP → Make a Request" (Make.com) com a URL da Graph API e o token no header ou como parâmetro.
Universal — qualquer endpointBatch Requests — múltiplas chamadas
A Graph API suporta até 50 chamadas em um único request via POST / com array de batch. Isso reduz latência e uso de limites de taxa quando você precisa buscar dados de várias Páginas ou campanhas simultaneamente.
// Nó: HTTP Request
Method: POST
URL: https://graph.facebook.com/v25.0/{{ $json.page_id }}/feed
// Body (JSON):
{
"message": "{{ $json.mensagem }}",
"access_token": "{{ $credentials.pageToken }}"
}
// Credenciais: Header Autenticação
// ou adicione access_token diretamente no Body
Limites de taxa e boas práticas
- ✓ 200 chamadas/hora por token de usuário — para maior volume, use System User Token (limites maiores baseados no número de usuários do app)
- ✓ Monitorar os headers de resposta:
X-App-Usageretorna o percentual do limite consumido. Implemente lógica para pausar requisições quando ultrapassar 80% - ✓ Use Batch Requests para múltiplas chamadas relacionadas — até 50 por batch, reduzindo chamadas de API e latência
- ✓ Implemente backoff exponencial: ao receber erro 4 (limite atingido) ou 17, aguarde e tente novamente com intervalo crescente (1s, 2s, 4s, 8s...)
- ✓ Use Webhooks em vez de polling para eventos como novos leads, comentários e mensagens — muito mais eficiente
- ! Nunca exponha tokens em código front-end — App Secret e tokens devem estar apenas no servidor (n8n, Make.com, backend)
Erros comuns da Graph API e como resolver
| Código | Significado | Como resolver |
|---|---|---|
Error 190 |
Token inválido ou expirado | Regenere o token. Para produção, use System User Token (não expira) |
Error 200 |
Sem permissão para este endpoint | Verifique as permissões do token no Debug Token — adicione o escopo necessário |
Error 4 |
Limite de taxa atingido | Aguarde e implemente backoff exponencial. Verifique header X-App-Usage |
Error 17 |
Limite de usuário atingido | Mesmo que erro 4 — backoff ou reduza frequência das chamadas |
Error 100 |
Parâmetro inválido | Verifique os campos obrigatórios. Consulte a documentação do endpoint específico |
Error 10 |
Permissão de desenvolvedor ausente | Para endpoints protegidos fora do modo dev, é necessária a App Review |
Error 368 |
Conta de anúncios desabilitada | A conta de anúncios foi suspensa. Contate o suporte do Meta Ads |
A Graph API conecta os sistemas — os cursos e artigos abaixo te mostram como usá-la na prática para anúncios, automações e criação de apps:
Curso n8n na Prática — Expert Digital
Aprenda a integrar a Graph API do Meta com n8n para automatizar publicações no Facebook e Instagram, buscar leads de formulários em tempo real via Webhook e criar dashboards de performance de anúncios conectados ao Google Sheets — tudo sem programar.
→ Acessar o curso completo de automações com n8nArtigo: Como Criar um App no Meta Developers
Para usar a Graph API você precisa de um App ID e de tokens de acesso — e tudo começa criando seu app no Meta Developers. Veja o guia completo: cadastro de conta de desenvolvedor, seleção de use cases, geração de tokens e configuração de permissões.
→ Ler o guia passo a passo no blogImersão IA e Automações — Expert Digital
A Graph API é uma das ferramentas do ecossistema de automações de marketing. Na Imersão IA e Automações da Expert Digital, você aprende a conectar Meta Ads, n8n, Make.com e IA generativa em fluxos completos — desde a captação de leads até o follow-up automático por WhatsApp.
→ Ver próximas datas e cidades disponíveisPerguntas frequentes (FAQ)
O que é a Graph API do Meta?
É a principal interface programática do Meta para ler e escrever dados no ecossistema Facebook e Instagram. Com ela é possível automatizar publicações de posts, buscar leads de formulários, acessar métricas de anúncios, responder comentários e configurar Webhooks de eventos em tempo real. A versão atual é v25.0, lançada em fevereiro de 2026.
Como autenticar na Graph API do Meta?
Use tokens OAuth 2.0. Para automações em produção, o mais indicado é o System User Token — gerado no Business Manager em Configurações → Usuários do Sistema, nunca expira e não depende de nenhum usuário humano. Para Páginas, o Page Access Token gerado a partir de um token de longa duração também não expira. Nunca use o token de usuário de 1 hora em automações.
Qual a versão atual da Graph API do Meta?
A versão atual é a v25.0, lançada em 18 de fevereiro de 2026. A URL base é https://graph.facebook.com/v25.0/. As versões v19 e v20 serão descontinuadas em maio e setembro de 2026 respectivamente. Sempre use a versão mais recente para evitar quebras.
Como usar a Graph API do Meta com n8n?
O n8n tem o nó nativo "Facebook Graph API" — configure as credenciais com seu token de acesso e use Method, URL e Body para montar qualquer chamada. Para leads em tempo real, use o nó "Facebook Lead Ads Trigger" que configura o Webhook automaticamente. Para publicações no Instagram, use o nó "HTTP Request" com os dois passos: criar container e publicar.
Como buscar leads do Facebook Lead Ads via Graph API?
Faça um GET para https://graph.facebook.com/v25.0/{form-id}/leads?fields=id,created_time,field_data&access_token={page-token}. O form-id é encontrado no Gerenciador de Formulários do Facebook. Para receber leads em tempo real sem polling, configure um Webhook para o objeto leadgen no painel do app — o Meta enviará cada novo lead ao seu endpoint em segundos.
Qual o limite de chamadas da Graph API?
O limite padrão é 200 chamadas por hora por token de usuário. Ao atingir o limite, a API retorna erro 4 ou 17. Para minimizar o uso: agrupe em Batch Requests (até 50 por chamada), use Webhooks em vez de polling e monitore o header X-App-Usage na resposta para saber o percentual do limite consumido.
A Graph API: a cola que conecta o Meta ao seu stack
Dominar a Graph API do Meta transforma o que antes era trabalho manual — publicar posts, exportar leads, verificar métricas — em fluxos automatizados que rodam 24h por dia sem intervenção humana.
Comece pequeno: configure o Webhook de leads e conecte ao n8n para disparar WhatsApp automaticamente. Depois automatize publicações de posts. Com o tempo, construa um dashboard de métricas de anúncios que atualiza sozinho. Cada peça que você automatiza é tempo liberado para estratégia.
Gostou do conteúdo? Compartilhe com quem está começando com automações no Meta! 🔗