API Facebook Stories de Meta

Ce document explique comment publier des stories sur les Pages Facebook à l’aide de l’API Facebook Stories.

Voici les étapes à suivre pour publier une story avec votre application :

1. Importer le contenu multimédia de l’utilisateur ou l’utilisatrice de votre application sur les serveurs Meta
2. Publier ce contenu multimédia en story sur la Page

Avant de commencer

Dans ce guide, nous partons du principe que vous avez lu la présentation de l’API Pages, implémenté les composants nécessaires et terminé la procédure décrite dans le guide de démarrage.

• Les utilisateur·ices de votre application devront pouvoir effectuer la tâche CREATE_CONTENT sur la Page indiquée dans le token d’accès, ainsi qu’accorder les autorisations suivantes à votre application :

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

Si vous utilisez un utilisateur système d’entreprise dans vos requêtes API, l’autorisation business_management est également requise.

Exigences concernant les contenus multimédias

Votre photo ou vidéo doit respecter les spécifications suivantes.

Spécifications relatives aux photos

Spécifications relatives aux vidéos

Limites

• La photo ou la vidéo importée ne doit pas déjà avoir été utilisée dans une publication.
• La durée maximale d’une story avec vidéo est de 60 secondes.
• Pour afficher les archives dans la liste de vos stories demandée avec GET, vous devez activer l’archive stories Facebook .

Recommandations

Les exemples de code contenus dans ce document ont été mis en forme pour plus de lisibilité. Remplacer les valeurs en gras et en italique, comme page_id, par vos propres valeurs.

Story avec vidéo

Pour publier une story avec vidéo sur une Page Facebook, vous devez initialiser une session d’importation d’une vidéo auprès des serveurs Meta, importer la vidéo sur les serveurs, puis publier la story.

Étape 1 : Initialiser une session

Pour initialiser une session d’importation, envoyez une requête POST au point de terminaison /page_id/video_stories, où page_id correspond à l’ID de la Page Facebook, avec le paramètre upload_phase défini sur start.

Exemple de requête

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

Si la requête aboutit, votre application reçoit une réponse JSON avec l’ID de la vidéo et l’URL de la Page Facebook sur laquelle importer la vidéo.

Exemple de réponse

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

Étape 2 : Importer une vidéo

Maintenant que vous avez initialisé une session d’importation et reçu l’URL, vous pouvez importer votre vidéo. Il est possible d’importer, au choix :

• un fichier vidéo hébergé sur un serveur HTTP/HTTPS public, par exemple un CDN ;
• un fichier vidéo local depuis votre appareil.

Importer un fichier hébergé

Pour importer un fichier hébergé, envoyez une requête POST au point de terminaison upload_url que vous avez reçu lors de l’initialisation, avec le paramètre suivant :

• file_url défini sur l’URL du fichier vidéo

Vérifiez que l’hôte est rupload.facebook.com.

L’API va désormais refuser tout fichier hébergé sur des sites dont l’accès est restreint via robots.txt. Les équipes de développement doivent s’assurer que le site d’hébergement autorise l’agent utilisateur "facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)" à récupérer le fichier hébergé.

Les fichiers hébergés sur le réseau de diffusion de contenu (CDN pour Content Delivery Network) Meta (par ex. les URL fbcdn) seront refusés. Les équipes de développement pourront utiliser à la place la fonctionnalité de crosspostage pour publier une vidéo sur plusieurs pages sans devoir l’importer vers chaque page. Consultez nos informations détaillées sur le crosspostage.

Exemple de requête

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

Importer un fichier local

Pour importer un fichier local, envoyez une requête POST au point de terminaison upload_url que vous avez reçu lors de l’initialisation, avec les paramètres suivants :

• offset défini sur 0
• file_size défini sur la taille totale, en octets, de la vidéo importée

Exemple de requête

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 la requête aboutit, votre application reçoit une réponse JSON dans laquelle success est défini sur true.

Exemple de réponse pour l’importation

{
    "success": true
}  

Importation interrompue

En cas d’interruption de l’importation de la vidéo, vous pouvez redémarrer le processus ou le reprendre.

• Pour redémarrer l’importation, renvoyez la requête POST et définissez offset sur 0.
• Pour reprendre l’importation, renvoyez la requête POST et définissez offset sur la valeur bytes_transfered figurant dans le rapport de vérification du statut de la vidéo.

Obtenir le statut de l’importation

Pour vérifier le statut de la vidéo en cours d’importation ou de publication, envoyez une requête GET au point de terminaison /video_id, avec le paramètre suivant :

• fields défini sur status

Exemple de requête

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

Si la requête aboutit, votre application reçoit une réponse JSON avec les éléments suivants :

• Un objet status qui contient :

  • video_status défini sur ready, processing, expired ou error
  • L’objet uploading_phase avec les paires clé/valeur suivantes :

    • status défini sur in_progress, not_started, complete ou error
    • bytes_transfered défini sur le nombre d’octets importés (peut être utilisé comme valeur pour offset en cas d’interruption de l’importation)
  • L’objet processing_phase avec les paires clé/valeur suivantes :

    • status défini sur in_progress, not_started, complete ou error
  • L’objet processing_phase avec les paires clé/valeur suivantes :

    • status défini sur in_progress, not_started, complete ou error
    • publish_status défini sur published ou not_published
    • publish_time défini sur la date et l’heure de publication au format UNIX

Exemple de réponse

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

Étape 3. Publier une story avec vidéo

Pour publier la story avec vidéo sur votre Page, envoyez une requête POST au point de terminaison /page_id/video_stories avec les paramètres suivants :

• video_id défini sur l’ID de la vidéo importée
• upload_phase défini sur finish

Exemple de requête

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

Si la requête aboutit, votre application reçoit une réponse JSON contenant les paires clé/valeur suivantes :

• success défini sur true
• post_id défini sur l’ID de votre publication en story

Exemple de réponse

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

Stories avec photo

Étape 1. Importer une photo

Consultez la référence sur les publications de Page  pour savoir comment importer une photo sur les serveurs Meta en utilisant le point de terminaison /page_id/photos. N’oubliez pas d’inclure le paramètre published et de le définir sur false.

Étape 2. Publier une story avec photo

Pour publier la story avec photo sur votre Page, envoyez une requête POST au point de terminaison /page_id/photo_stories avec les paramètres suivants :

• photo_id défini sur l’ID de la photo importée

Exemple de requête

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

Si la requête aboutit, votre application reçoit une réponse JSON contenant les paires clé/valeur suivantes :

• success défini sur true
• post_id défini sur l’ID de votre publication en story

Exemple de réponse

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

Obtenir les stories

Pour obtenir la liste de toutes les stories d’une Page, ainsi que des données sur chaque story, envoyez une requête GET au point de terminaison /page_id/stories, où page_id correspond à l’ID de la Page concernée.

Exemple de requête

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

En cas de réussite, votre application reçoit une réponse JSON avec un tableau d’objets. Chaque objet contient des informations concernant une story publiée sur la Page, fournies dans les paires clé/valeur suivantes :

• post_id défini sur l’ID de la publication en story
• status défini sur PUBLISHED ou ARCHIVED
• creation_time défini sur la date et l’heure de publication de la story au format UNIX
• media_type défini sur video ou photo
• media_id défini sur l’ID de la vidéo ou de la photo intégrée dans la publication en story
• url défini sur l’URL Facebook de la publication en story, par exemple https://facebook.com/stories/8283482737484972

Exemple de réponse

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

Il est possible de filtrer les stories en fonction de leur statut (publié ou archivé) et de la date (à l’aide des paramètres since et until).

Voir aussi

Apprenez-en plus sur les points de terminaison et les concepts abordés dans ce guide.

Guides pertinents

• Utilisateur système d’entreprise
• Facebook Login
• Facebook Login for Business
• API Graph – Résultats paginés avec since et until

Références sur les points de terminaison

• Référence sur les Pages
• Référence sur les stories avec vidéo sur les Pages
• Référence sur les stories avec photo sur les Pages
• Référence sur les vidéos
• Référence Statistiques des stories