Facebook Stories API von Meta

In diesem Dokument erfährst du, wie du mithilfe der Facebook Stories API auf Facebook-Seiten Stories veröffentlichen kannst.

Um eine Story zu veröffentlichen, muss deine App die folgenden Schritte durchführen:

1. Die Medien deines*deiner App-Nutzer*in auf die Meta-Server hochladen
2. Die Medien als Story auf der Seite deines*deiner App-Nutzer*in veröffentlichen

Bevor du beginnst

Bei diesem Leitfaden wird vorausgesetzt, dass du die Übersicht zur Pages API gelesen und die erforderlichen Komponenten implementiert sowie den Leitfaden zu den ersten Schritten erfolgreich abgeschlossen hast.

• Deine App-Nutzer*innen müssen auf der Seite, die im Seiten-Zugriffsschlüssel angegeben ist, die Aufgabe CREATE_CONTENT durchführen können und deiner App die folgenden Berechtigungen erteilen:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

Wenn du in deinen API-Anfragen einen geschäftlichen Systemnutzer verwendest, brauchst du auch die Berechtigung business_management.

Medienanforderungen

Du musst ein Foto oder Video angeben, das den folgenden Spezifikationen entspricht.

Fotospezifikationen

Videospezifikationen

Einschränkungen

• Ein für eine Story hochgeladenes Foto oder Video darf nicht in einem zuvor veröffentlichten Beitrag verwendet worden sein
• Eine Video-Story darf nicht länger als 60 Sekunden dauern
• Um archivierte Storys in deine GET-Anfragen zum Anzeigen einer Liste deiner Storys aufzunehmen, musst du dein Facebook-Story-Archiv auf aktivieren.

Best Practices

Die Codebeispiele in diesem Dokument wurden so formatiert, dass sie gut lesbar sind. Ersetze Werte in Fett- oder Kursivschrift wie page_id durch deine Werte.

Video-Stories

Um eine Video-Story auf einer Facebook-Seite zu veröffentlichen, startest du eine Video-Upload-Sitzung mit Meta-Servern, lädst das Video auf Meta-Server hoch und veröffentlichst dann die Video-Story.

Schritt 1: Sitzung starten

Um eine Upload-Sitzung zu starten, sende eine POST-Anfrage an den /page_id/video_stories-Endpunkt, wobei page_id die ID für deine Facebook-Seite ist. Der Parameter upload_phase muss dabei auf start festgelegt sein.

Beispielanfrage

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

Bei Erfolg erhält deine App eine JSON-Antwort mit der ID für das Video und der Facebook-URL, unter der du das Video hochlädst.

Beispielantwort

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

Schritt 2: Video hochladen

Nachdem du nun eine Upload-Sitzung gestartet und die Upload-URL erhalten hast, kannst du dein Video hochladen. Du hast zwei Möglichkeiten:

• Du kannst eine gehostete Videodatei auf einem öffentlichen http/https-Server wie einem CDN hochladen.
• Du kannst eine lokale Videodatei von deinem Gerät hochladen.

Eine gehostete Datei hochladen

Um eine gehostete Datei hochzuladen, sende eine POST-Anfrage an den upload_url-Endpunkt, den du im Initialisierungsschritt erhalten hast. Diese sollte die folgenden Parameter enthalten:

• file_url festgelegt auf die URL für deine Videodatei

Stelle sicher, dass der Host rupload.facebook.com ist.

Die API lehnt jetzt Dateien ab, die auf Sites gehostet werden, die den Zugriff über robots.txt einschränken. Entwickler*innen müssen sicherstellen, dass die Hosting-Site den Nutzer-Agent „facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)“ zulässt, um die gehostete Datei abzurufen.

Auf Meta CDN gehostete Dateien (z. B. fbcdn-URLs) werden abgelehnt. Stattdessen können Entwickler*innen das Crossposting-Feature verwenden, um ein Video auf mehreren Seiten zu veröffentlichen, ohne das Video auf jede einzelne Seite hochzuladen. Mehr über das Crossposten erfährst du in unserer detaillierten Anleitung.

Beispielanfrage

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

Eine lokale Datei hochladen

Um eine lokale Datei hochzuladen, sende eine POST-Anfrage an den upload_url-Endpunkt, den du im Initialisierungsschritt erhalten hast. Diese sollte die folgenden Parameter enthalten:

• offset festgelegt auf 0
• file_size festgelegt auf die Gesamtgröße des hochgeladenen Videos in Byte

Beispielanfrage

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

Bei erfolgreichem Upload erhält deine App eine JSON-Antwort, bei der success auf true gesetzt ist.

Beispielantwort für Upload

{
    "success": true
}  

Unterbrochener Upload

Wenn der Video-Upload unterbrochen wurde, kannst du den Upload entweder neu starten oder fortsetzen.

• Um den Upload fortzusetzen, sende erneut die POST-Anfrage und lege offset auf 0 fest.
• Um den Upload fortzusetzen, sende die POST-Anfrage erneut, wobei offset auf den bytes_transfered-Wert aus einer Status-Prüfung festgelegt ist.

Upload-Status abrufen

Um den Status deines Videos zu prüfen, sende während des Uploads oder der Veröffentlichung eine GET-Anfrage an den /video_id-Endpunkt. Schließe den folgenden Parameter ein:

• fields festgelegt auf status

Beispielanfrage

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

Wenn der Vorgang erfolgreich verläuft, erhält deine App eine JSON-Antwort, die Folgendes enthält:

• Ein status-Objekt, das Folgendes enthält:

  • video_status mit dem Wert ready, processing, expired oder error
  • uploading_phase-Objekt mit den folgenden Schlüssel-Wert-Paaren:

    • status festgelegt auf in_progress, not_started, complete oder error
    • bytes_transfered festgelegt auf die hochgeladenen Byte. Kann als Wert für offset verwendet werden, wenn der Upload unterbrochen wurde.
  • processing_phase-Objekt mit den folgenden Schlüssel-Wert-Paaren:

    • status festgelegt auf in_progress, not_started, complete oder error
  • processing_phase-Objekt mit den folgenden Schlüssel-Wert-Paaren:

    • status festgelegt auf in_progress, not_started, complete oder error
    • publish_status festgelegt auf published oder not_published
    • publish_time festgelegt auf den UNIX-Zeitstempel der tatsächlichen Zeit oder des Zeitpunkts der Veröffentlichung

Beispielantwort

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

Schritt 3: Eine Video-Story veröffentlichen

Um auf deiner Seite eine Video-Story zu veröffentlichen, sende eine POST-Anfrage an den /page_id/video_stories-Endpunkt und füge folgende Parameter hinzu:

• video_id festgelegt auf die ID für dein hochgeladenes Video
• upload_phase festgelegt auf finish

Beispielanfrage

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

Wenn der Vorgang erfolgreich verläuft, erhält deine App eine JSON-Antwort, die die folgenden Schlüssel-Wert-Paare enthält:

• success festgelegt auf true
• post_id festgelegt auf die ID deines Story-Beitrags

Beispielantwort

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

Foto-Stories

Schritt 1: Ein Foto hochladen

In der Referenz zu Seitenbeiträgen erfährst du, wie du mit dem /page_id/photos-Endpunkt ein Foto auf Meta-Server hochladen kannst. Schließe unbedingt den Parameter published ein und lege ihn auf false fest.

Schritt 2: Eine Foto-Story veröffentlichen

Um auf deiner Seite eine Foto-Story zu veröffentlichen, sende eine POST-Anfrage an den /page_id/video_stories-Endpunkt und füge folgende Parameter hinzu:

• video_id festgelegt auf die ID deines hochgeladenen Videos

Beispielanfrage

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

Wenn der Vorgang erfolgreich verläuft, erhält deine App eine JSON-Antwort, die die folgenden Schlüssel-Wert-Paare enthält:

• success festgelegt auf true
• post_id festgelegt auf die ID deines Story-Beitrags

Beispielantwort

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

Abrufen von Stories

Um eine Liste aller Stories für eine Seite und Daten zu jeder Story abzurufen, sende eine GET-Anfrage an den /page_id/stories-Endpunkt, wobei page_id die ID für die Seite ist, die du anzeigen möchtest.

Beispielanfrage

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

Bei Erfolg erhält deine App eine JSON-Antwort mit einem Array von Objekten, wobei jedes Objekt Informationen über eine auf der Seite veröffentlichte Story enthält. Jedes Objekt enthält die folgenden Schlüssel-Wert-Paare:

• Die post_id festgelegt auf die ID des veröffentlichten Story-Beitrags
• Der status festgelegt auf PUBLISHED, ARCHIVED
• Die creation_time festgelegt auf den UNIX-Zeitstempel, zu dem die Story veröffentlicht wurde
• Der media_type festgelegt auf video oder photo
• Die media_id festgelegt auf die ID des Videos oder Fotos in dem Story-Beitrag
• Die url festgelegt auf die Facebook-URL für den Story-Beitrag wie z. B. https://facebook.com/stories/8283482737484972

Beispielantwort

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

Du kannst Stories mit den Parametern since und until nach Status, veröffentlicht oder archiviert und Datum filtern.

Siehe auch

In diesem Leitfaden findest du weitere Informationen zu den Endpunkten und Konzepten, die in diesem Dokument erwähnt wurden.

Relevante Leitfäden

• Geschäftlicher Systemnutzer
• Facebook Login
• Facebook Login for Business
• Graph API – Paginierte Ergebnisse mit seit und bis

Endpunktreferenzen

• Seitenreferenz
• Referenz zu Seitenvideo-Stories
• Referenz zu Seitenfoto-Stories
• Videoreferenz
• Referenz zu Stories-Insights