API de Facebook Stories de Meta

En este documento, te mostramos cómo usar la API de Facebook Stories para publicar historias en páginas de Facebook.

Para publicar una historia, tu app deberá seguir estos pasos:

1. Sube el contenido multimedia del usuario de tu app a los servidores de Meta
2. Publica el contenido multimedia en la página del usuario de tu app como historia

Antes de empezar

En esta guía, se asume que leíste la información general sobre la API de páginas, implementaste los componentes necesarios y completaste correctamente la guía de primeros pasos.

• Deberás implementar el inicio de sesión con Facebook o el inicio de sesión con Facebook para empresas si quieres solicitar a los usuarios de tu app los permisos necesarios para acceder a sus páginas de Facebook y recibir tokens de acceso a las páginas.
• Es necesario que los usuarios de tu app puedan realizar la tarea CREATE_CONTENT en la página que se muestra en el token de acceso a la página y otorgar a tu app los siguientes permisos:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

Si utilizas un usuario del sistema comercial en tus solicitudes a la API, es necesario que también cuentes con el permiso business_management.

Requisitos relacionados con el contenido multimedia

Debes proporcionar una foto o un video que cumpla con las siguientes especificaciones.

Especificaciones de fotos

Especificaciones de videos

Limitaciones

• No se pueden usar en historias fotos o videos que ya se compartieron en una publicación.
• Una historia de video no puede superar los 60 segundos.
• Si deseas incluir historias archivadas en tus solicitudes GET para ver una lista de tus historias, debes activar tu archivo de historias de Facebook

Prácticas recomendadas

Se modificó el formato de los ejemplos de códigos que se incluyen en este documento a fin de facilitar la lectura. Reemplaza los valores en negrita y cursiva, como page_id, por tus propios valores.

Historias de video

Si deseas publicar una historia de video en una página de Facebook, deberás inicializar una sesión para subir un video a los servidores de Meta, subirlo allí y, luego, publicar la historia.

Paso 1: Inicializar la sesión

A fin de inicializar una sesión para subir contenido, envía una solicitud POST al punto de conexión /page_id/video_stories, donde page_id es el identificador de tu página de Facebook, con el parámetro upload_phase configurado en start.

Ejemplo de solicitud

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

Si la solicitud se procesa correctamente, tu app recibe una respuesta JSON con el identificador del video y la URL de Facebook donde subirás el video.

Ejemplo de respuesta

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

Paso 2: Subir un video

Ahora que inicializaste una sesión para subir contenido y recibiste la URL, puedes subir el video. Tienes dos opciones:

• Subir un archivo de video alojado en un servidor http/https público, como un CDN.
• Subir un archivo de video local desde tu dispositivo.

Subir un archivo alojado

Para subir un archivo alojado, envía una solicitud POST al punto de conexión upload_url que recibiste en el paso de inicialización e incluye los siguientes parámetros:

• file_url configurado en la URL de tu archivo de video.

Asegúrate de que el host sea rupload.facebook.com.

La API ahora rechaza los archivos de sitios que restringen el acceso mediante robots.txt. Los desarrolladores deben asegurarse de que el sitio de alojamiento permita que el agente de usuario “facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)” busque el archivo alojado.

Se rechazarán los archivos alojados en la red de distribución de contenido Meta CDN (por ejemplo, las URL fbcdn). En su lugar, los desarrolladores pueden usar la función de publicación cruzada para publicar un video en varias páginas sin necesidad de subirlo en cada una por separado. Consulta nuestra guía detallada sobre publicación cruzada.

Ejemplo de solicitud

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

Subir un archivo local

Para subir un archivo local, envía una solicitud POST al punto de conexión upload_url que recibiste en el paso de inicialización e incluye los siguientes parámetros:

• offset configurado en 0.
• file_size configurado en el tamaño total en bytes del video que se está subiendo.

Ejemplo de solicitud

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"

Si se sube correctamente, tu app recibirá una respuesta JSON con success configurado en true.

Ejemplo de respuesta de subida

{
    "success": true
}  

Subida interrumpida

Si se interrumpe la subida del video, puedes reiniciarla o reanudarla.

• Para reiniciarla, vuelve a enviar la solicitud POST y configura offset en 0.
• Para reanudarla, vuelve a enviar la solicitud POST con offset configurado en el valor bytes_transfered de una comprobación de estado.

Obtener el estado de subida

Para comprobar el estado del video, envía una solicitud GET al punto de conexión /video_id mientras se sube o publica con el siguiente parámetro:

• fields configurado en status.

Ejemplo de solicitud

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

Si la operación se completa correctamente, la app recibe una respuesta JSON que incluye lo siguiente:

• Un objeto status que contiene:

  • video_status con un valor de ready, processing, expired o error.
  • El objeto uploading_phase con los siguientes pares clave-valor:

    • status configurado en in_progress, not_started, complete o error.
    • bytes_transfered configurado en los bytes que se subieron. Se puede usar como el valor de offset si se interrumpe la subida.
  • El objeto processing_phase con los siguientes pares clave-valor:

    • status configurado en in_progress, not_started, complete o error.
  • El objeto processing_phase con los siguientes pares clave-valor:

    • status configurado en in_progress, not_started, complete o error.
    • publish_status configurado en published o not_published.
    • publish_time configurado en una marca de tiempo UNIX de la hora real o publicada.

Ejemplo de respuesta

{
  "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"
    }
  }
}

Paso 3. Publicar una historia de video

Para publicar la historia de video en tu página, debes enviar una solicitud POST al punto de conexión /page_id/video_stories con los siguientes parámetros:

• video_id configurado en el identificador del video que subiste.
• upload_phase configurado en finish.

Ejemplo de solicitud

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

Si la operación se completa correctamente, la app recibe una respuesta JSON que incluye los siguientes pares clave-valor:

• success configurado en true.
• post_id configurado en el identificador de la publicación de tu historia.

Ejemplo de respuesta

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

Historias de foto

Paso 1. Subir una foto

Visita la referencia de publicaciones de la página para obtener información sobre cómo subir una foto a los servidores de Meta mediante el punto de conexión /page_id/photos. Asegúrate de incluir el parámetro published configurado en false.

Paso 2. Publicar una historia de foto

Para publicar la historia de foto en tu página, debes enviar una solicitud POST al punto de conexión /page_id/photo_stories con los siguientes parámetros:

• photo_id configurado en el identificador de la foto que subiste.

Ejemplo de solicitud

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

Si la operación se completa correctamente, la app recibe una respuesta JSON que incluye los siguientes pares clave-valor:

• success configurado en true.
• post_id configurado en el identificador de la publicación de tu historia.

Ejemplo de respuesta

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

Obtener historias

Para obtener una lista de todas las historias de una página y datos referidos a las historias, envía una solicitud GET al punto de conexión /page_id/stories, donde page_id es el identificador de la página que quieres ver.

Ejemplo de solicitud

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

Si la solicitud se procesa correctamente, tu app recibe una respuesta JSON con una matriz de objetos en la que cada uno contiene información sobre una historia publicada en la página. Cada objeto incluye los siguientes pares clave-valor:

• El post_id configurado en el identificador de la historia publicada.
• El status configurado en PUBLISHED y ARCHIVED.
• La creation_time configurada en la marca de tiempo UNIX de cuando se publicó la historia.
• El media_type configurado en video o photo.
• El media_id configurado en el identificador del video o de la foto de la publicación de la historia.
• La url configurada en la URL de Facebook de la publicación de la historia, como https://facebook.com/stories/8283482737484972.

Ejemplo de respuesta

{
  "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…"
    },
    ...
  ],
}

Puedes filtrar las historias por estado (publicadas o archivadas) o por fecha mediante los parámetros since y until.

Consulta también

Obtén más información sobre los puntos de conexión y los conceptos analizados en esta guía.

Guías relevantes

• Usuario del sistema comercial
• Inicio de sesión con Facebook
• Inicio de sesión con Facebook para empresas
• API Graph: Resultados paginados con "since" y "until"

Referencias de puntos de conexión

• Referencia de la página
• Referencia de las historias de video de la página
• Referencia de las historias de foto de la página
• Referencia de video
• Referencia de estadísticas de historias