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 :

  1. Importer le contenu multimédia sur les serveurs Meta
  2. Publier le 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.

  • Vous devrez installer Facebook Login ou Facebook Login for Business afin de demander aux utilisateurs et utilisatrices de votre application les autorisations nécessaires pour accéder à leurs Pages Facebook et recevoir des tokens d’accès de Page.

  • 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·e utilisateur·ice 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

PropriétéSpécification

Type de fichier

.jpeg, .bmp, .png, .gif, .tiff

Taille du fichier

4 Mo maximum. Il est conseillé de ne pas dépasser 1 Mo pour les fichiers .png afin d’éviter la pixélisation de l’image.

Spécifications relatives aux vidéos

PropriétéSpécification

Type de fichier

.mp4 (recommandé)

Proportions

9 x 16

Résolution

1 080 x 1 920 pixels (recommandé), 540 x 960 pixels minimum

Fréquence d’images

24 à 60 images/seconde

Durée

3 à 90 secondes,

60 secondes maximum pour un reel publié en story sur une Page Facebook

Paramètres vidéo

  • Sous-échantillonnage chromatique 4:2:0
  • GOP fermé (2 à 5 secondes)
  • Compression : H.264, H.265 (codecs VP9 et AV1 également acceptés)
  • Fréquence d’images fixe
  • Balayage progressif

Paramètres audio

  • Débit audio : 128 Kbit/s ou plus
  • Voies : stéréo
  • Codec : AAC à faible complexité
  • Taux d’échantillonnage : 48 kHz

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

Lorsque vous testez un appel d’API, vous pouvez inclure le paramètre access_token, défini sur votre token d’accès. En revanche, lorsque vous effectuez des appels sécurisés depuis votre application, utilisez la classe de token d’accès.

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 demande

curl -X POST "https://graph.facebook.com/v21.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/v21.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 :

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
Exemple de demande
curl -X POST "https://rupload.facebook.com/video-upload/v21.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 demande
curl -X POST "https://rupload.facebook.com/video-upload/v21.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 demande
curl -X GET "https://graph.facebook.com/v21.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
La réponse suivante montre que le fichier a bien été importé.
{
  "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 
    }
  }
}
La réponse suivante montre qu’une erreur s’est produite pendant la phase de traitement.
{
  "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 demande

curl -X POST "https://graph.facebook.com/v21.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 demande

curl -X POST "https://graph.facebook.com/v21.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 demande

    
curl -i -X GET "https://graph.facebook.com/v21.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).