O que é um token de acesso da Página do Facebook e por que ele começa com uma pessoa

O que é um token de acesso da Página do Facebook?

A Meta define o token de acesso da Página do Facebook como a credencial que permite a um app agir como uma Página, e não como uma pessoa. O guia de tokens de acesso resume isso em uma linha: "Page access tokens let you read, write, and modify data belonging to a Facebook Page." Publicar no feed de uma Página, responder comentários como a Página e ler o Page Insights dependem desse token.

A Meta lista cinco tipos de token na mesma página, e o token de Página é o único vinculado a uma única Página:

O token de Página também é o que a Pages API pede pelo nome. A visão geral da Pages API da Meta diz "Most endpoints require Page access tokens," e a tabela de erros da Pages API tem um código para quem chama um desses endpoints com qualquer outra coisa: 190 com subcódigo 2069032, "A Page access token is required for this call."

Como obter um token de acesso da Página?

Você obtém um token de acesso da Página trocando um User access token por ele. A instrução da Meta tem duas etapas: "To obtain one, first get a user access token, then exchange it for a Page access token via the Graph API." Não existe endpoint que emita um token de Página para um app que ainda não fez o login de uma pessoa.

A troca é um único GET no edge accounts da pessoa:

curl -i -X GET "https://graph.facebook.com/{your-user-id}/accounts?access_token={user-access-token}"

A Meta diz que a chamada "returns a list of Pages you have a role on, including the Page category, your permissions on each Page, and the Page access token." Cada objeto no array data traz access_token, category, category_list, name, id e um array tasks:

{
  "data": [
    {
      "access_token": "EAACEdE...",
      "category": "Brand",
      "name": "Ash Cat Page",
      "id": "1353269864728879",
      "tasks": ["ANALYZE", "ADVERTISE", "MODERATE", "CREATE_CONTENT", "MANAGE"]
    }
  ]
}

A visão geral da Pages API descreve o mesmo fluxo em quatro etapas: obter um User access token "through Facebook Login for Business," consultar /me/accounts, guardar o ID da Página e o token retornados e depois "use the ID and token to query the Page node." Um único login pode retornar várias Páginas. Nesse caso, a Meta orienta os desenvolvedores a "capture each Page ID and its respective token", porque cada Página recebe sua própria string.

Por que publicar na Página de uma empresa exige um login pessoal no Facebook?

Publicar na Página de uma empresa exige um login pessoal porque o token de Página herda sua autoridade de uma pessoa. A visão geral da Meta define a condição: "In order to get a token from an app User, the app User must own or be able to perform a Task on the Page." A Página em si nunca faz login em lugar nenhum. Quem faz é uma pessoa com uma função nela, e o token registra quem foi essa pessoa.

A Meta descreve esse vínculo de duas formas um pouco diferentes em duas páginas ativas. O guia de tokens de acesso diz que os tokens de Página "are unique to each Page, admin, and app combination." A visão geral da Pages API diz que eles são "unique to each Page, app User, and app." Na prática, a leitura é a mesma. Mude a Página, a pessoa ou o app e você terá um token diferente. Se a pessoa que conectou a Página perder a função, as chamadas feitas com o token dela deixam de passar na verificação de tarefa, que é uma das causas explicadas em por que um agendador de redes sociais continua desconectando.

O único caminho que dispensa um login pessoal é um system user. A configuração do Facebook Login for Business da Meta permite que um app solicite "a User access token or System-user access token." Escolha o User token e "your app users will log in using their personal Facebook account." Escolha o token de system user e eles "will be required to log in using a business portfolio," o que, segundo a Meta, "is only required if this configuration needs continuous access to business assets, such as Facebook Pages." Tokens de system user dependem de o portfólio empresarial ser dono da Página ou tê-la compartilhada, então servem para agências e equipes internas com o Business Manager configurado, e não ajudam em nada um criador solo cuja Página está ligada a um perfil pessoal.

Quais permissões um token de acesso da Página precisa?

Para publicar, um token de acesso da Página precisa de duas concessões separadas: as permissões que a pessoa aprova para o app e uma tarefa que a pessoa tem na Página. A Meta verifica as duas. A visão geral explica a segunda verificação: "we will first check if the User has been approved for a task that permits that type of action."

Estas são as permissões de Página que uma integração de publicação solicita, com as descrições da própria Meta na referência de permissões:

As tarefas retornadas no array tasks correspondem a ações. CREATE_CONTENT permite que uma pessoa "Publish content as the Page on the Page." MODERATE cobre responder e excluir comentários. ANALYZE cobre o Insights. MANAGE permite que uma pessoa "Assign and manage Page tasks." A Meta acrescenta que "If a person is given Admin access to a Page in the UI, that person is able to perform all tasks on that Page." Se o app tem pages_manage_posts mas a pessoa não tem CREATE_CONTENT, a Pages API retorna 1 com subcódigo 2853006, "Viewer doesn't have permission to perform this action."

Os próprios guias da Meta discordam em um nome. O guia Get Started da Pages API lista quatro permissões para a primeira publicação: pages_manage_metadata, pages_manage_posts, pages_manage_read_engagement e pages_show_list. A referência de permissões não tem nenhuma entrada chamada pages_manage_read_engagement. O guia Manage a Page lista pages_read_engagement no lugar, que também é a dependência que a referência indica para pages_manage_posts. Solicite pages_read_engagement.

O App Review fica por cima de tudo isso. A visão geral diz "All Page-related Permissions and Features require approval through the App Review process before your app can use them when your app goes live." Apps em modo de desenvolvimento podem solicitar qualquer permissão, mas só de pessoas que têm uma função no app.

O token de acesso da Página do Facebook expira?

Um token de acesso da Página do Facebook expira no mesmo prazo do User token que o originou, até você usar um User token de longa duração, quando o token de Página deixa de ter data de expiração. As duas metades disso vêm da Meta, em páginas diferentes.

A visão geral da Pages API acrescenta uma terceira afirmação que não se encaixa na tabela. Ela diz que os tokens de acesso da Página "have an expiration time," sem ressalva para o caso de longa duração. A página sobre tokens de longa duração diz o contrário para tokens derivados de um User token de longa duração. Leia a linha da visão geral como uma descrição do token padrão de curta duração e verifique um token real com debug_token antes de confiar em qualquer uma das páginas. A chamada de troca, o valor 5183944 de expires_in e os campos de debug_token estão explicados na nota sobre o token de acesso de longa duração do Facebook e seu relógio de 60 dias.

"Sem data de expiração" não significa permanente. A ressalva geral da Meta sobre a duração dos tokens também vale aqui. Ela diz "Do not depend on these lifetimes remaining the same," porque "they may change without warning or expire early." O guia de depuração da Meta nomeia os gatilhos que documenta. Uma pessoa que "logged out of your app or changed their password" recebe o código 190, subcódigo 460, e um app que a pessoa desautorizou recebe o subcódigo 458. Qualquer um dos dois encerra um token de Página que nunca teve data.

Um token de acesso da Página muda o funcionamento dos limites de taxa?

Sim. Chamadas feitas com um token de acesso da Página contam para um limite diferente das chamadas feitas com um User token. A Meta mede as requisições da Pages API feitas com um token de Página ou de system user pelo limite de taxa de business use case, Calls within 24 hours = 4800 * Number of Engaged Users, em que engaged users são as pessoas "who engaged with the Page per 24 hours." Requisições feitas com User tokens ou tokens de app ficam sob o limite de taxa de plataforma, mais antigo. A fórmula e o cabeçalho X-Business-Use-Case-Usage estão explicados na nota sobre o limite de taxa de business use case da Meta para Páginas.

Perguntas frequentes

Qual endpoint retorna um token de acesso da Página?

GET /{user-id}/accounts, ou GET /me/accounts, chamado com um User access token. A resposta traz um objeto por Página com access_token, name, id, category e as tasks que a pessoa pode executar nessa Página.

Dá para obter um token de acesso da Página sem uma conta pessoal no Facebook?

Só por meio de um system user. As configurações do Facebook Login for Business da Meta podem solicitar um token de system user, o que exige que as pessoas façam login com um portfólio empresarial. Para isso funcionar, o portfólio precisa ser dono da Página ou ter acesso a ela.

O token de acesso da Página é o mesmo para todos os administradores de uma Página?

Não. A Meta diz que os tokens de acesso da Página "are unique to each Page, admin, and app combination." Dois administradores que conectam o mesmo app à mesma Página geram dois tokens diferentes.

Por que meu token de Página diz que nunca expira, mas parou de funcionar?

A Meta diz que os tokens de Página de longa duração "only expire or are invalidated under certain conditions." O guia de depuração associa o subcódigo 460 a uma pessoa que "logged out of your app or changed their password" e o subcódigo 458 a um app que a pessoa não autoriza mais. Os dois encerram o token sem que nenhuma data seja atingida.

Qual permissão permite que um app publique em uma Página?

pages_manage_posts, que a Meta descreve como a permissão para um app "create, edit and delete your Page posts." Ela depende de pages_read_engagement e pages_show_list, e a pessoa também precisa da tarefa CREATE_CONTENT na Página.

Que erro aparece ao chamar um endpoint de Página com um User token?

A Pages API retorna o código 190 com subcódigo 2069032 e a mensagem "A Page access token is required for this call." Use o token de Página da resposta de /accounts e tente de novo.

Qual é a diferença entre um token de acesso de usuário e um token de acesso da Página?

Um token de acesso de usuário lê ou grava "a person's Facebook data on their behalf", enquanto um token de acesso da Página lê, grava e modifica "data belonging to a Facebook Page". O token de usuário vem de uma caixa de login e você o troca pelo token da Página por meio de /accounts. A maioria dos endpoints da Pages API exige o token da Página.

Um token de acesso da Página precisa passar pelo App Review?

Sim, antes de o seu app entrar no ar. A Meta diz que todas as permissões e recursos relacionados a Páginas exigem aprovação pelo App Review nesse momento. No modo de desenvolvimento, um app pode pedir qualquer permissão, mas só de pessoas que tenham uma função no app.

O que acontece com um token de Página quando o administrador que o conectou perde a função?

As chamadas desse token deixam de passar pela verificação de tarefas que as deixava entrar. Os tokens de Página são únicos para cada combinação de Página, administrador e app, então o token pertence a essa pessoa. Se você conectar de novo com alguém que ainda tenha a tarefa certa, recebe um token diferente.

Como saber se um token de acesso da Página ainda é válido?

Passe o token por debug_token e leia o resultado, em vez de confiar em uma das duas afirmações da Meta sobre expiração. Isso vale também para tokens sem data de expiração, porque um logout, uma troca de senha ou uma desautorização podem encerrá-los.