
Guias de integração
Guia da API do LinkedIn
Guia da API de e-mail
Guia da API do WhatsApp
Fale com vendas
Como obter cada token, estendê-lo para cerca de 60 dias, verificá-lo com debug_token e tratar o erro 190, e como um SaaS pode dispensar todo o fluxo de tokens.
graph.facebook.com/debug_token?input_token={USER_ACCESS_TOKEN} applicationSeu appis_validtrueexpires_atem 60 diastoken de usuário de longa duraçãodata_access_expires_atem 90 diasrenovado quando o usuário está ativoscopesSem refresh token: verifique, depois peça novo login
Um token de acesso da API do Facebook é a string que toda chamada à Graph API exige. Você obtém um token de usuário pelo Facebook Login (ou pelo Graph API Explorer, para testes), troca-o no seu servidor por um token de longa duração de cerca de 60 dias e depois chama /me/accounts para obter os tokens de Página. Não existe chave de API nem refresh token: monitore os tokens com debug_token e trate o erro 190.
Para um SaaS que atende muitos clientes, existe um segundo modelo: os usuários conectam as próprias contas do Facebook pela Unipile, e o seu app nunca guarda um token da Meta.
Nenhum token da Meta para obter, estender ou depurar
Conecte a conta
O seu usuário conecta a conta do Facebook ou a Página uma única vez pelo Hosted Auth. Sem app da Meta, sem App Review.
Chame com a sua chave de API
Envie X-API-KEY com o account_id do usuário: GET /v2/{ACCOUNT_ID}/chats.
Acompanhe um único status
Verifique products_connection_status; se necessário, o usuário se reconecta pelo Hosted Auth.
A Meta define um access token como "uma string opaca que identifica um usuário, um app ou uma Página do Facebook". Toda requisição à Graph API leva um, e o tipo dele determina em nome de quem você age.
| Token | Age em nome de | Como obter | Duração e uso |
|---|---|---|---|
| Usuário | Uma pessoa logada | Facebook Login ou Graph API Explorer | 1 a 2 horas, ou cerca de 60 dias |
| Página | Uma Página do Facebook | /me/accounts com o token de usuário de um admin | Segue o token de usuário |
| App | O seu app da Meta | Chamada client_credentials, ou {APP_ID}|{APP_SECRET} | Só chamadas servidor a servidor |
| Usuário do sistema | A sua empresa | Business Settings | Sem expiração, ou 60 dias |
| Cliente | O seu app, no código cliente | App Dashboard | Não é um segredo |
/me/accounts com o token de usuário de um adminclient_credentials, ou {APP_ID}|{APP_SECRET}O Instagram tem o próprio fluxo: veja o nosso guia do token da API do Instagram.
Fonte: guia Access Tokens da Meta. Última verificação: 17 de novembro de 2026.
Não existe chave de API do Facebook: toda chamada usa um access token. Para testes, gere um para a sua própria conta no Graph API Explorer. Em produção, os usuários entram no seu app da Meta com o Facebook Login (for Business, quando você precisa das Páginas deles), e o seu servidor troca o code retornado por um user access token.
developers.facebook.com/tools/explorer/dialog/oauth com client_id, redirect_uri, statecode/oauth/access_token com o code e o App SecretA resposta traz access_token, token_type e expires_in. Outras pessoas só podem conceder permissões depois que o App Review dá Advanced Access ao seu app. O caminho de acesso completo está no nossa visão geral da API do Facebook, e o lado das Páginas no nosso guia da API de Páginas do Facebook.
Fonte: guia Manually Build a Login Flow da Meta (Graph API v27.0). Última verificação: 17 de novembro de 2026.
Envie o token de usuário de curta duração para GET /oauth/access_token com grant_type=fb_exchange_token, o seu App ID e o seu App Secret. A resposta traz um token de longa duração e o seu expires_in, cerca de 60 dias. A Meta é explícita: "faça essa chamada a partir do seu servidor, não de um cliente".
As abas 1 a 3 usam a Graph API da Meta; a aba 4 é a Unipile, sem token da Meta.
# Server side only: this call carries your App Secret
curl -G "https://graph.facebook.com/oauth/access_token" \
-d "grant_type=fb_exchange_token" \
-d "client_id={APP_ID}" \
-d "client_secret={APP_SECRET}" \
-d "fb_exchange_token={USER_ACCESS_TOKEN}"
# Response (abridged)
{ "access_token": "{LONG_LIVED_USER_TOKEN}", "expires_in": 5183944 }
# App access token, for server-to-server calls such as debug_token
curl -G "https://graph.facebook.com/oauth/access_token" \
-d "client_id={APP_ID}" \
-d "client_secret={APP_SECRET}" \
-d "grant_type=client_credentials"
# Or pass it directly, without the call
access_token={APP_ID}|{APP_SECRET}
# Check any token with your app token
curl -G "https://graph.facebook.com/debug_token" \
-d "input_token={LONG_LIVED_USER_TOKEN}" \
-d "access_token={APP_ID}|{APP_SECRET}"
# Response (abridged)
{ "data": {
"app_id": "{APP_ID}",
"is_valid": true,
"expires_at": 1800057600,
"data_access_expires_at": 1802649600,
"scopes": ["public_profile", "pages_show_list"]
} }
# No Meta token: your API key and the user's account_id
curl --request GET \
--url "https://api.unipile.com/v2/{ACCOUNT_ID}/inboxes" \
--header "X-API-KEY: {API_KEY}"
# List the chats of the connected account
curl --request GET \
--url "https://api.unipile.com/v2/{ACCOUNT_ID}/chats" \
--header "X-API-KEY: {API_KEY}"
Requisições extraídas dos guias Long-Lived Access Tokens e Access Tokens da Meta. Unipile: documentação de Páginas do Facebook.
Com o token de usuário de longa duração de um admin da Página, GET /me/accounts retorna cada Página com o próprio token, que "não tem data de expiração e só expira ou é invalidado em certas condições". Detalhes no nosso guia da API de Páginas do Facebook; para publicar com ele, veja como publicar em uma Página com o token dela.
Segundo a Meta, um token de usuário de curta duração dura de uma a duas horas e um de longa duração cerca de 60 dias. Os tokens de Página obtidos a partir de um token de longa duração e alguns tokens de usuário do sistema não têm data de expiração. À parte disso, o seu acesso aos dados de um usuário termina após 90 dias de inatividade.
A Meta afirma que "o período de expiração do acesso aos dados é de 90 dias, com base na última vez em que o usuário esteve ativo". O usuário continua logado, mas o seu app não consegue ler os dados dele até que ele autorize o app de novo.
Nenhum token é permanente: um token que "nunca expira" ainda deixa de funcionar quando o usuário remove o seu app, muda a senha ou perde a função. A Meta avisa: "não conte com que essas durações permaneçam as mesmas".
Fontes: Access Tokens, Long-Lived Access Tokens, Authorization vs. data access e tokens de usuário do sistema da Meta. Última verificação: 17 de novembro de 2026.
Um token de acesso de usuário do sistema pertence a um usuário do sistema do seu Business Manager, não a uma pessoa. Segundo a Meta, ele permite que "o seu app execute ações programáticas e automatizadas em objetos de anúncio ou Páginas". Você o gera no Business Settings.
Sem renovação, para os casos em que um vazamento do token é um risco aceitável.
Defina set_token_expires_in_60_days=true e renove com fb_exchange_token antes do dia 60.
Fontes: Install apps and generate tokens e Access Tokens da Meta. Última verificação: 17 de novembro de 2026.
Chame GET /debug_token?input_token={TOKEN} com um app access token (ou o token de usuário de um desenvolvedor do app). A resposta traz a validade, a expiração, a expiração do acesso aos dados e as permissões concedidas. Sem código, cole o token no Access Token Debugger (developers.facebook.com/tools/debug/accesstoken).
0 significa sem data de expiração.granular_scopes acrescenta os IDs de destino.Para verificar se um access token do Facebook é válido em produção, execute a requisição da aba 3 do bloco de código acima no seu servidor, de forma agendada, e armazene as duas datas com cada token. Uma permissão ausente em scopes explica a maioria dos bugs do tipo "funciona para mim, falha para eles".
Fonte: referência do debug_token da Meta (Graph API v27.0). Última verificação: 17 de novembro de 2026.
O erro 190 significa que o access token do Facebook expirou ou é inválido. Ele chega como OAuthException, e o seu error_subcode indica o que pedir ao usuário. Tentar de novo com o mesmo token nunca resolve.
{ "error": { "type": "OAuthException", "code": 190, "error_subcode": 460, "fbtrace_id": "EJplcsCHuLu" } }
Leia o error_subcode, guarde o fbtrace_id para o suporte da Meta
| Subcódigo | Significado | O que fazer |
|---|---|---|
| 458 | App não instalado | Peça um novo login ao usuário |
| 459 | Usuário em checkpoint | O usuário entra no facebook.com |
| 460 | Senha alterada | Peça um novo login ao usuário |
| 463 | Token expirado | Novo login, depois nova troca |
| 464 | Usuário não confirmado | O usuário entra no facebook.com |
| 467 | Token inválido | Reconecte o usuário |
| 492 | Sem função adequada na Página | Novo token de um admin atual |
Em um SaaS com vários clientes, o 492 é o clássico: o admin que conectou uma Página sai da empresa. Os outros códigos estão na nossa tabela de erros da API do Facebook.
Fonte: guia de tratamento de erros da Graph API da Meta. Última verificação: 17 de novembro de 2026.
Trate cada access token do Facebook como a senha da conta por trás dele: mantenha o App Secret e os tokens de app no seu servidor, criptografe os tokens de usuário e de Página em repouso, assine as chamadas do servidor com appsecret_proof e exclua os tokens assim que um cliente se desconectar.
appsecret_proof. A Meta o define como "um hash sha256 do seu access token, usando o app secret como chave"; ative Require App Secret no App Dashboard.expires_at.Fontes: guias Access Tokens e Securing Requests da Meta. Última verificação: 17 de novembro de 2026.
Com a Unipile, cada usuário conecta a própria conta do Facebook uma única vez, pelo Hosted Auth. As Páginas que ele gerencia chegam no mesmo account_id, e você chama a API com a sua própria chave (X-API-KEY). Sem token da Meta, sem app da Meta e sem App Review do seu lado.
| Pergunta | Access tokens da Meta | Conta conectada à Unipile |
|---|---|---|
| O que você armazena | Um token por usuário, mais um por Página, admin e app | Um account_id por usuário e uma chave de API |
| O que você monitora | expires_at e data_access_expires_at de cada token | Um status por Página em metadata.products_connection_status |
| O que você renova | Troca por longa duração ou login antes do dia 60 | Nenhum token da Meta para trocar |
| No erro 190 | Analisar o subcódigo e pedir um novo login ao usuário | O usuário se reconecta pelo Hosted Auth, se necessário |
account_id por usuário e uma chave de APIexpires_at e data_access_expires_at de cada tokenmetadata.products_connection_statusUma conta conectada cobre mensagens, caixas de entrada de Páginas, posts, comentários e reações. Uma Página pode responder às suas conversas e publicar posts, mas não pode iniciar uma conversa. Veja a aba 4 acima e a nossa página da API do Facebook Messenger.
Cada usuário conecta a própria conta
A Unipile é uma empresa independente, não é um app oficial da Meta nem um Meta Partner. Ela age em nome de cada usuário autenticado, e cada usuário continua sujeito aos termos da Meta.
Desenvolva no Facebook sem um fluxo de tokens
Cada usuário vincula a própria conta do Facebook uma única vez; você usa uma só API para Facebook, LinkedIn, WhatsApp e e-mail. Teste grátis de 7 dias.
Cada usuário conecta a própria conta, sem armazenamento de perfis. A Unipile não é Meta Partner. Saiba mais
Todos os endpoints da API do Facebook em um só lugar
Depois que a conta estiver conectada, veja todos os endpoints do Facebook disponíveis com a Unipile, ou leia o guia completo da API do Facebook para permissões, limites e erros.
Respostas rápidas sobre duração, renovação, verificação de validade, armazenamento de tokens e o erro 190.
Não de verdade. Um token de usuário de longa duração dura cerca de 60 dias. Os tokens de Página obtidos a partir dele e alguns tokens de usuário do sistema não têm data de expiração, mas ainda deixam de funcionar quando o usuário remove o seu app, muda a senha ou perde a função. Preveja um fluxo de reconexão.
Não no sentido do OAuth: a Meta não documenta nenhum grant refresh_token para o Facebook Login. Você troca um token de curta duração ainda válido com fb_exchange_token; depois que um token expira, o usuário faz login de novo. Em apps móveis nativos, a Meta renova os tokens de longa duração uma vez por dia quando a pessoa usa o seu app.
Porque 60 dias é um teto, não uma promessa. Um token deixa de funcionar antes quando o usuário muda a senha, remove o seu app, cai em um checkpoint de segurança ou perde a função na Página, e a Meta avisa que as durações "podem mudar sem aviso ou expirar antes". Leia o error_subcode do erro 190 para saber em qual caso você está.
Chame GET /debug_token?input_token={TOKEN} com o seu app access token e leia is_valid, expires_at, data_access_expires_at e scopes. Para uma verificação pontual, cole o token no Access Token Debugger da Meta.
Sim, se você os tratar como senhas: criptografe-os em repouso, mantenha-os fora dos logs e do código cliente, e use o App Secret e os tokens de app apenas em chamadas servidor a servidor. Assine as chamadas do servidor com appsecret_proof.
O erro 190 com o subcódigo 492 indica uma sessão inválida: o usuário por trás de um Page access token não tem mais uma função adequada na Página. Obtenha um novo token de Página de um admin atual.
Não. A Unipile é uma empresa independente: não é Meta Partner, não é um app oficial da Meta e não é endossada, patrocinada nem aprovada pela Meta. Facebook é uma marca registrada da Meta Platforms, Inc.
Não. Você chama a Unipile com a sua chave de API e o account_id de cada usuário conectado. Os usuários vinculam a conta do Facebook e as Páginas que gerenciam pela autenticação hospedada da Unipile: sem app da Meta, App Secret nem App Review do seu lado.
Ela foi projetada em conformidade com o Digital Markets Act: cada usuário conecta a própria conta, e a Unipile age em nome dele sem armazenar perfis de usuários. Saiba mais na nossa página sobre o Digital Markets Act.
Sim. Cada conta conectada continua sujeita aos Termos de Serviço da Meta. Use a API para cenários legítimos, como atendimento ao cliente, CRM e conversas diretas; spam e automação não autorizada podem levar à restrição das contas.
Ainda tem dúvidas? Nossa equipe está aqui para ajudar.
Fale com um especialista