API do Facebook Stories da Meta

Este documento mostra como usar a API do Facebook Stories para publicar stories em Páginas do Facebook.

Para publicar um story, seu app seguirá as seguintes etapas:

1. Carregue a mídia do usuário do seu app nos servidores da Meta
2. Publique a mídia na Página do usuário do app como um story

Antes de começar

Neste guia, presumimos que você tenha lido a visão geral da API de Páginas e implementado os componentes necessários, além de ter concluído o guia de introdução.

• Os usuários do app deverão ser capazes de executar a tarefa CREATE_CONTENT na Página representada no token de acesso à Página e conceder ao seu app as seguintes permissões:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

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

Requisitos de mídia

Você precisa fornecer uma foto ou um vídeo que atenda às especificações a seguir.

Especificações para fotos

Especificações para vídeos

Limitações

• Não é possível carregar uma mídia de foto ou vídeo que já tenha sido usada em um post.
• O story de vídeo pode ter no máximo 60 segundos.
• Para incluir stories arquivados nas solicitações GET e ver uma lista completa, habilite o arquivo de stories do Facebook .

Boas práticas

Os exemplos de código exibidos neste documento foram formatados para facilitar a leitura. Substitua os valores em negrito e itálico (como page_id) pelos seus valores.

Stories de vídeo

Para publicar um story de vídeo em uma Página do Facebook, será preciso inicializar uma sessão de carregamento de vídeo com os servidores da Meta, carregar o vídeo nesses servidores e depois publicar o story.

Etapa 1: inicializar a sessão

Para inicializar uma sessão de carregamento, envie uma solicitação POST ao ponto de extremidade /page_id/video_stories, em que page_id é a identificação da sua Página do Facebook, com o parâmetro upload_phase definido como start.

Exemplo de solicitação

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

Se a solicitação for bem-sucedida, o app receberá uma resposta JSON com o ID do vídeo e o URL do Facebook onde o vídeo será carregado.

Exemplo de resposta

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v25.0/video_id",
}  

Etapa 2: carregar um vídeo

Depois de inicializar a sessão de carregamento e receber o URL, será possível carregar o vídeo. Você pode carregar:

• um arquivo de vídeo hospedado em um servidor http/https público, como uma CDN;
• um arquivo de vídeo local do seu dispositivo.

Carregar um arquivo hospedado

Para carregar um arquivo hospedado, envie uma solicitação POST ao ponto de extremidade upload_url recebido na etapa de inicialização com os seguintes parâmetros:

• file_url definido como o URL do arquivo de vídeo.

O host precisa ser rupload.facebook.com.

A API agora rejeitará os arquivos hospedados em sites que restringem o acesso pelo arquivo robots.txt. Os desenvolvedores precisam garantir que o site de hospedagem permita que o agente de usuário “facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)” busque pelo arquivo hospedado.

Arquivos hospedados na CDN da Meta (por exemplo, URLs do fbcdn) serão rejeitados. Como alternativa, os desenvolvedores podem usar o recurso de post cruzado para compartilhar um vídeo em várias páginas sem carregá-lo em cada uma delas. Consulte nossas orientações detalhadas sobre post cruzado.

Exemplo de solicitação

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

Carregar um arquivo local

Para carregar um arquivo local, envie uma solicitação POST ao ponto de extremidade upload_url recebido na etapa de inicialização com os seguintes parâmetros:

• offset definido como 0.
• file_size definido como o tamanho total em bytes do vídeo que está sendo carregado.

Exemplo de solicitação

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

Se o carregamento for bem-sucedido, o app receberá uma resposta JSON com success definido como true.

Exemplo de resposta do carregamento

{
    "success": true
}  

Carregamento interrompido

Se o carregamento do vídeo for interrompido, será possível reiniciar ou retomar o processo.

• Para reiniciar, envie novamente a solicitação POST e defina offset como 0.
• Para retomar, envie outra vez a solicitação POST com offset definido como o valor bytes_transfered de uma verificação de status.

Consultar o status do carregamento

Para verificar o status do vídeo, durante o processo de carregamento ou publicação, envie uma solicitação GET ao ponto de extremidade /video_id com o parâmetro a seguir:

• fields definido como status.

Exemplo de solicitação

curl -X GET "https://graph.facebook.com/v25.0/video_id" \
	-d "fields=status"

Se a solicitação for bem-sucedida, o app receberá uma resposta JSON contendo o seguinte:

• Um objeto status que inclui:

  • video_status com um valor de ready, processing, expired ou error.
  • O objeto uploading_phase com estes pares de chave-valor:

    • status definido como in_progress, not_started, complete ou error.
    • bytes_transfered definido como os bytes que foram carregados. Pode ser usado como o valor de offset quando o carregamento é interrompido.
  • O objeto processing_phase com estes pares de chave-valor:

    • status definido como in_progress, not_started, complete ou error.
  • O objeto processing_phase com estes pares de chave-valor:

    • status definido como in_progress, not_started, complete ou error.
    • publish_status definido como published ou not_published.
    • publish_time definido como um registro de data e hora UNIX, indicando o tempo atual ou da publicação.

Exemplo de resposta

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

Etapa 3: publicar um story de vídeo

Para publicar um story de vídeo na sua Página, envie uma solicitação POST ao ponto de extremidade /page_id/video_stories com os seguintes parâmetros:

• video_id definido como o ID do vídeo que foi carregado.
• upload_phase definido como finish.

Exemplo de solicitação

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

Se a solicitação for bem-sucedida, o app receberá uma resposta JSON contendo estes pares de chave-valor:

• success definido como true.
• post_id definido como a identificação do post do story.

Exemplo de resposta

{
  "success": true,
  "post_id": 1234
}

Stories de foto

Etapa 1: carregar uma foto

Acesse a referência de publicações na Página para saber como carregar uma foto nos servidores da Meta usando o ponto de extremidade /page_id/photos. Importante: inclua o parâmetro published e defina-o como false.

Etapa 2: publicar um story de foto

Para publicar um story de foto na sua Página, envie uma solicitação POST ao ponto de extremidade /page_id/photo_stories com os seguintes parâmetros:

• photo_id definido como o ID da foto que foi carregada.

Exemplo de solicitação

curl -X POST "https://graph.facebook.com/v25.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

Se a solicitação for bem-sucedida, o app receberá uma resposta JSON contendo estes pares de chave-valor:

• success definido como true.
• post_id definido como a identificação do post do story.

Exemplo de resposta

{
  "success": true,
  "post_id": 1234
}

Recuperar stories

Para recuperar a lista de todos os stories de uma Página, assim como dados sobre cada story, envie uma solicitação GET ao ponto de extremidade /page_id/stories, em que page_id é a identificação da Página que você quer visualizar.

Exemplo de solicitação

    
curl -i -X GET "https://graph.facebook.com/v25.0/page_id/stories"

Se a solicitação for bem-sucedida, o app receberá uma resposta JSON com uma matriz de objetos, e cada objeto conterá informações sobre um story publicado na Página. Os objetos incluem os seguintes pares de chave-valor:

• post_id definido como a identificação do post do story.
• status definido como PUBLISHED, ARCHIVED.
• creation_time definido como um registro de data e hora UNIX, indicando quando o story foi publicado.
• media_type definido como video ou photo.
• media_id definido como o ID do vídeo ou da foto no post do story.
• url definido como o URL do Facebook para o post do story (por exemplo, https://facebook.com/stories/8283482737484972).

Exemplo de resposta

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

Você pode filtrar os stories por data e status (publicado ou arquivado) usando os parâmetros since e until.

Veja também

Saiba mais sobre os pontos de extremidade e conceitos abordados neste guia.

Guias relevantes

• Usuários do sistema
• Login do Facebook
• Login do Facebook para Empresas
• Resultados paginados: Paginação com base no cursor

Referências de ponto de extremidade

• Page
• Page Video Stories
• Page Photo Stories
• Video
• Stories Insights