API de Páginas do Facebook

Gerenciar uma Página

Este documento mostra como executar as seguintes tarefas em uma Página do Facebook:

  • Obter uma lista das Páginas em que você pode executar uma tarefa, incluindo:
    • Tarefas específicas que você pode executar em cada Página
    • Tokens de acesso para cada Página que você pode usar para testar chamadas de API​
  • Obter e atualizar os detalhes sobre uma Página
  • Obter e atualizar as configurações de uma Página
  • Receber notificações sobre alterações sugeridas que a Meta implementará em uma Página
    • Aceitar ou rejeitar as alterações sugeridas
  • Obter avaliações de uma Página
  • Bloquear uma pessoa em uma Página

Antes de começar

Para usar este guia, pressupomos que você já tenha lido a Visão geral da API de Páginas.

Para uma pessoa que pode realizar tarefas na Página, você terá de implementar o Login do Facebook para solicitar as seguintes permissões e receber um token de acesso à Página ou do usuário:

  • pages_manage_engagement
  • pages_manage_metadata
  • pages_manage_posts
  • pages_read_engagement
  • pages_read_user_engagement
  • pages_show_list
  • A permissão publish_video (se estiver publicando um vídeo na Página)

Se você estiver utilizando um usuário do sistema comercial nas suas solicitações de API, a permissão business_management também será necessária.

O usuário do app deve poder realizar as tarefas CREATE_CONTENT, MANAGE e/ou MODERATE na Página nas solicitações de API.

Boas práticas

Ao testar uma chamada de API, você pode incluir o parâmetro access_token definido como seu token de acesso. No entanto, quando fizer chamadas seguras do seu app, use as classes de token de acesso.

Os exemplos de solicitação foram formatados para facilitar a leitura. Substitua os valores em negrito e itálico (como page_id) pelos seus valores.

Páginas, tarefas e tokens

Uma única chamada de API é capaz de fornecer muitas informações sobre Páginas nas quais você pode executar uma tarefa.

Obter suas Páginas

Para acessar uma lista de todas as Páginas nas quais você pode executar tarefas, ver as tarefas que você pode executar em cada Página e obter um token de acesso de curta duração para cada Página, envie uma solicitação GET para o ponto de extremidade /user_id/accounts usando um token de acesso do usuário.

Exemplo de solicitação

curl -i -X GET 
     "https://graph.facebook.com/user_id/accounts"

Em caso de sucesso, o app receberá uma resposta JSON com uma matriz de objetos da Página. Cada objeto da Página contém:

  • O nome da Página
  • A identificação da Página
  • A categoria da Página, o nome da categoria e a identificação
  • Um token de acesso à Página de curta duração
  • Todas as tarefas que o usuário pode executar na Página

Exemplo de resposta

{
  "data": [
    {
      "access_token": "{facebook-for-developers-page-access-token}",
      "category": "Internet Company",
      "category_list": [
        {
          "id": "2256",
          "name": "Internet Company"
        }
      ],
      "name": "Facebook for Developers",
      "id": "{facebook-for-developers-page-id}",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT"
      ]
    },
    {
      "access_token": "{my-outlandish-stories-page-access-token}",
      "category": "Blogger",
      "category_list": [
        {
          "id": "361282040719868",
          "name": "Blogger"
        }
      ],
      "name": "My Outlandish Stories",
      "id": "{my-outlandish-stories-page-id}",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
...
  ]
}

Obter tarefas para outras pessoas

Caso você possa executar a tarefa MANAGE na Página, será possível obter uma lista das outras pessoas que podem realizar tarefas nessa mesma Página, incluindo as tarefas que cada uma delas pode executar.

Para obter uma lista de pessoas e as tarefas que elas podem realizar na Página, envie uma solicitação GET para o ponto de extremidade /page_id/roles.

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/page_id/roles"

Em caso de sucesso, o app receberá uma resposta JSON com o nome da pessoa, o ID no escopo da Página e as tarefas que cada pessoa pode realizar em uma Página.

Exemplo de resposta

{
  "data": [
    {
      "name": "Person One",
      "id": "page_scoped_id_for_one"
        "tasks": [
          "ANALYZE"
        ]
    },
    {
      "name": "Person Two",
      "id": "page_scoped_id_for_two",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
...
  ],
}

Detalhes da Página

Se você puder executar a tarefa MANAGE na Página, será possível usar um token de acesso à Página para visualizar detalhes de uma Página, como sobre, email, horário de funcionamento, entre outros. Caso seu app tenha sido aprovado para o recurso Acesso ao Conteúdo Público da Página, você também poderá usar um token de acesso do usuário para consultar essas informações.

Obter os detalhes

Para obter detalhes sobre uma Página, envie uma solicitação GET para o ponto de extremidade /page_id com o parâmetro fields definido como os detalhes da Página que você gostaria de visualizar.

Observação: você pode usar o ponto de extremidade /pages/search para encontrar identificações de Páginas quando estiver usando o recurso Acesso ao Conteúdo Público da Página.

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/page_id \
     ?fields=about,attire,bio,location,parking,hours,emails,website"

Em caso de sucesso, o app receberá uma resposta JSON com valor para os campos solicitados. Um campo não retornado na resposta indica que a Página não tem esse valor definido. Por exemplo, se a Página não tiver definido o campo attire, ele não aparecerá na resposta.

Atualizar os detalhes

Caso você possa executar a tarefa MANAGE na Página, será possível usar o token de acesso à Página para enviar uma solicitação POST para o ponto de extremidade /page_id com os parâmetros que você quer atualizar, como about.

Exemplo de solicitação

curl -i -X POST "https://graph.facebook.com/v21.0/page_id" \
     -H "Content-Type: application/json" \
     -d '{
           "about":"This is an awesome cafe located downtown!",
         }'

Em caso de sucesso, o app receberá uma resposta JSON com success definido como true.

Alterações sugeridas pela Meta

Eventualmente, a Meta sugerirá alterações nos detalhes da sua Página (como corrigir um erro de digitação ou atualizar as categorias) para que as pessoas possam encontrá-la com mais facilidade. Para receber essas notificações, você deve assinar o webhook page_upcoming_change e/ou page_change_proposal.

Depois de receber a notificação, você poderá tomar as seguintes medidas:

  • Não fazer nada, e as alterações entrarão em vigor no horário designado na notificação
  • Aceitar as alterações, e elas entrarão em vigor imediatamente
  • Rejeitar as alterações, e nenhuma alteração será feita

Aceitar ou rejeitar uma alteração sugerida

Para aceitar ou rejeitar uma alteração sugerida, envie uma solicitação POST para o ponto de extremidade /page_change_proposal_id com o campo accept definido como true para aceitar a alteração ou como false para rejeitá-la. A page_change_proposal_id é o valor proposal.id que você recebeu na notificação de webhook page_upcoming_change ou o valor value.id recebido na notificação de webhook page_change_proposal.

curl -i -X POST "https://graph.facebook.com/v21.0/page_change_proposal_id" \
     -H "Content-Type: application/json" \
     -d '{
           "accept":"true",
         }'

Em caso de sucesso, o app receberá uma resposta JSON com success definido como true.

Configurações da Página

Caso você possa executar a tarefa MANAGE na Página, será possível usar um token de acesso à Página para enviar uma solicitação GET para o ponto de extremidade /page_id/settings e obter uma lista de todas as configurações da Página em questão.

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/v21.0/page_id/settings"

Em caso de sucesso, o app receberá uma resposta JSON com uma matriz de objetos, em que cada objeto setting é definido como uma configuração da Página com o valor true ou false.

Exemplo de resposta

{
  "data": [
    {
      "setting": "USERS_CAN_POST",
      "value": false
    },
    {
      "setting": "USERS_CAN_MESSAGE",
      "value": true
    },
    {
      "setting": "USERS_CAN_POST_PHOTOS",
      "value": true
    },
    ...
  ]
}

Atualizar uma configuração

Para atualizar as configurações de uma Página, envie uma solicitação POST para o ponto de extremidade /page_id/settings com o parâmetro option definido como a configuração que você quer atualizar.

Exemplo de solicitação

curl -i -X POST "https://graph.facebook.com/v21.0/page_id/settings" \
     -H "Content-Type: application/json" \
     -d '{
           "option":{"USERS_CAN_MESSAGE": "true"},
         }'

Em caso de sucesso, o app receberá uma resposta JSON com success definido como true.

Obter as avaliações

Para obter as avaliações de uma Página, incluindo o nome do avaliador, o respectivo ID no escopo da Página, o tipo de recomendação (positiva ou negativa) e o texto da avaliação, envie uma solicitação GET para o ponto de extremidade /page_id/ratings.

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/page_id/ratings"

Em caso de sucesso, o app receberá uma matriz JSON com objetos de avaliação. Cada objeto contém:

  • created_time definido como a hora em que a avaliação foi criada
  • recommendation_type definido como positive ou negative
  • review_text definido como o conteúdo da avaliação
  • um objeto reviewer com o name e a id da pessoa que escreveu a avaliação
{
  "data": [
    {
      "created_time": "unixtimestamp",
      "recommendation_type": "positive",
      "review_text": "I love this page!",
      "reviewer": {
        "name": "Person One",
        "id": "psid_for_one"
      }
    },
    {
      "created_time": "unixtimestamp",
      "recommendation_type": "positive",
      "review_text": "This page is wonderful!",
      "reviewer": {
        "name": "Person Two",
        "id": "psid_for_two"
      }
    },
...
  ]
}

Bloquear uma pessoa

Para impedir que uma pessoa comente em uma Página, envie uma solicitação POST para o ponto de extremidade /page_id/blocked com o parâmetro user definido como o ID no escopo da Página da pessoa que você quer bloquear.

Exemplo de solicitação

curl -i -X POST "https://graph.facebook.com/v21.0/page_id/blocked"
     -H "Content-Type: application/json" \
     -d '{
           "user":"psid_to_block",
         }'

Em caso de sucesso, o app receberá uma resposta JSON com o ID no escopo da Página definido como true.

{
 "psid_to_block": true
}

Próximas etapas

Saiba como publicar links, fotos e vídeos na sua Página.

Veja também

Referências