Meta dokumentiert vier verschiedene Limits für Facebook scheduled_publish_time

Was ist Facebook scheduled_publish_time?

Das Feld Facebook scheduled_publish_time ist der Graph-API-Parameter, der Meta mitteilt, wann ein unveröffentlichter Seitenbeitrag live gehen soll, und du sendest ihn im selben POST, der den Beitrag erstellt. Es gibt ihn auf /{page-id}/feed für Text- und Linkbeiträge, auf /{page-id}/videos für Videos und auf /{page-id}/photos für Fotos.

Metas Posts-Leitfaden der Pages API führt ihn als Unterpunkt von published, und das ist das Erste, was man darüber verstehen muss: „published set to true to publish the post immediately (default) or false to publish later“. Direkt unter dieser Zeile steht: „Include scheduled_publish_time if set to false“.

Die Beispielanfrage des Leitfadens sieht so aus:

curl -X POST "https://graph.facebook.com/v25.0/page_id/feed" \
  -H "Content-Type: application/json" \
  -d '{
    "message":"your_message_text",
    "link":"your_url",
    "published":"false",
    "scheduled_publish_time":"unix_time_stamp_of_a_future_date",
  }'

Bei Erfolg ist die Antwort die ID eines Beitrags, der existiert, aber noch nicht auf der Seite erschienen ist: {"id": "page_post_id"}. Der Rest dieser Seite behandelt die drei Dinge, die entscheiden, ob diese Anfrage funktioniert: das Flag published, das Zeitformat und die Vorlaufzeit.

Setzt scheduled_publish_time published=false voraus?

Ja. Ein geplanter Seitenbeitrag ist ein unveröffentlichter Beitrag mit einem Datum, also gehören die beiden Parameter zusammen. Lässt du published auf dem Standardwert true, geht der Beitrag sofort raus.

Fotos brauchen einen zusätzlichen Schritt. Die Page-Photos-Referenz sagt, dass ein Foto für einen geplanten Beitrag mit temporary=true hochgeladen werden muss, und beschreibt diesen Parameter in einer Zeile: „published must be false, and you can't set scheduled_publish_time“. Der Zeitplan gehört an den Feed-Beitrag, der die Fotos anhängt, nicht an die Fotos selbst. Für einen Beitrag mit mehreren Fotos schreibt Meta: „When the photos are part of a scheduled post, the published, scheduled_publish_time, and unpublished_content_type parameters must be included.“ Das Beispiel dazu sendet published=false, scheduled_publish_time=1512068400 und unpublished_content_type=SCHEDULED an /feed.

Lade diese Fotos kurz vor dem Erstellen des Beitrags hoch. Meta stellt fest, dass ein unveröffentlichter Upload „will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them.“

Einen Ausrutscher in der Page-Feed-Referenz solltest du kennen, bevor du Code daraus kopierst. Ihre Parametertabelle nennt das Flag published, während ihr Abschnitt „Posting a Link to a Page“ dich anweist: „Set the publish parameter to 1 to publish the post immediately or to 0 to create an unpublished post to be published later“. Die Beispielanfrage unter diesem Satz sendet published=1. Nimm published.

Welche Zeitformate akzeptiert scheduled_publish_time?

Der Posts-Leitfaden der Pages API nennt drei Formate:

Der Linktext des Leitfadens schreibt den Standard „ISO 8061“. Der Link selbst zeigt auf ISO 8601, und das Beispiel ist ein gültiger ISO-8601-String, also ist das als Tippfehler zu lesen.

Die Referenzseiten sind enger gefasst als der Leitfaden. Die Page-Feed-Referenz typisiert den Parameter als timestamp und nennt ihn einen „UNIX timestamp indicating when post should go live.“ Die Referenzen zu Page Photos und Page Videos typisieren ihn beide als int64. Nur der Leitfaden erwähnt Strings. Ein UNIX-Integer in Sekunden ist das einzige Format, das jede Seite akzeptiert, also sende das. JavaScripts Date.now() liefert Millisekunden, also eine 1.000-mal zu große Zahl, deshalb vor dem Senden teilen.

Wenn du doch einen relativen String verwendest, sagt Meta dir, wie du das Ergebnis prüfst: „If you are relying on strtotime()'s relative date strings you can read-after-write the scheduled_publish_time of the created post to make sure it is what is expected.“ tomorrow hängt davon ab, welche Serveruhr und welche Zeitzone den String parst, und Meta sagt zu beidem nichts.

Auch das Zurücklesen des Werts hat eine Eigenheit. In der Feldliste der Page-Feed-Referenz heißt das lesende Feld sheduled_publish_time, ohne das „c“, und ist als float typisiert. Die Page-Post-Referenz schreibt es korrekt als scheduled_publish_time. Frage die korrekte Schreibweise ab.

Wie weit im Voraus kann man mit scheduled_publish_time planen?

Mindestens 10 Minuten. Das Maximum hängt davon ab, welche Meta-Seite du liest, und die Seiten widersprechen sich.

Die Untergrenze von 10 Minuten ist die einzige Zahl, bei der sich alle einig sind. Mastodons Untergrenze ist halb so groß, und die Dokumentation sagt es in einer Zeile, „Must be at least 5 minutes in the future“, deshalb braucht scheduled_at in der Mastodon API 5 Minuten Vorlauf.

Der Widerspruch bei /feed wiegt am schwersten, weil Textbeiträge, Linkbeiträge und geplante Beiträge mit mehreren Fotos alle darüber laufen. Zwei Meta-Seiten nennen zwei Obergrenzen für denselben Parameter am selben Endpunkt: Der Leitfaden sagt 30 Tage, die Referenz sagt 75. Keine der beiden Seiten sagt, welche aktuell ist, und keine erwähnt die Zahl der anderen. Ein Tool, das 75 Tage erlaubt, funktioniert, wenn die Referenz stimmt, und scheitert irgendwo zwischen Tag 31 und Tag 75, wenn der Leitfaden stimmt. Ein Tool mit einer Grenze von 30 Tagen funktioniert in beiden Fällen. Begrenze auf 30.

Auch die Videozahl verdient einen zweiten Blick. Die Feed-Seiten messen ab „the time of the API request“. Die Videoreferenz misst ab „the time of publishing the video“, was bei einem Video, dessen Upload erst Minuten nach der auslösenden Anfrage fertig wird, mehrdeutig ist. Lass an beiden Enden Spielraum.

Metas Foto- und Videoreferenzen listen außerdem mehr unveröffentlichte Zustände auf, als sie erklären. Beide Seiten führen unpublished_content_type-Werte wie SCHEDULED, SCHEDULED_RECURRING, DRAFT und PUBLISH_PENDING auf, und keine sagt, was SCHEDULED_RECURRING bewirkt. Bleib bei SCHEDULED.

Welchen Fehler gibt Meta zurück, wenn die Zeit außerhalb des Bereichs liegt?

Meta veröffentlicht keinen. Keine der Seiten oben zitiert eine Fehlermeldung für einen scheduled_publish_time, der zu früh oder zu spät liegt. Die Referenzen zu Page Videos und Page Post nennen beide den Fehler 100, „Invalid parameter“, als allgemeinen Validierungsfehler, und genauer wird Metas Dokumentation nicht.

Baue deine Fehlerbehandlung um den Code herum. Metas eigene Fehlerreferenz der Marketing API nennt den Grund in einer Zeile: „Error handling should be done using only the Error Codes. The Description string is subject to change without prior notice.“ Protokolliere die Felder message und fbtrace_id fürs Debugging, aber knüpfe die Retry-Logik an code. Metas Leitfaden zur Fehlerbehandlung beschreibt fbtrace_id als „Internal support identifier“, also den Wert, den du dem Meta-Support gibst.

Eine Ablehnung wegen des Zeitfensters ist außerdem kein wiederholbarer Fehler. Wer dieselbe Anfrage wiederholt, sendet denselben falschen Zeitstempel und bekommt dieselbe 100. Prüfe das Fenster vor dem Aufruf: mindestens 10 Minuten und höchstens 30 Tage im Voraus für /feed, gemessen an der Uhr deines Servers in UTC-Sekunden. YouTube plant Uploads über andere Felder mit anderen Fehlerbildern, und jedes Feld in YouTubes Planungsablauf und wie es scheitert, ist separat beschrieben.

Wie ändert oder storniert man einen geplanten Facebook-Beitrag?

Aktualisiere ihn mit einem POST an /{page_post_id} oder lösche ihn mit einem DELETE an denselben Pfad. Die Update-Parameter der Page-Post-Referenz enthalten sowohl scheduled_publish_time als auch is_published, aber die Tabelle beschreibt keinen der beiden über seinen eigenen Namen hinaus. Der Pages-API-Leitfaden fügt eine Einschränkung hinzu: „An app can only update a Page post if the post was made using that app.“ Nach dieser Regel kann deine App einen in Meta Business Suite geplanten Beitrag nicht bearbeiten.

Um geplante Beiträge zu finden, lies /{page-id}/feed mit dem Feld is_published. Die Page-Feed-Referenz sagt es direkt: „Published and unpublished posts will be returned when querying the /{page-id}/feed endpoint. Use the 'is_publishedfield to return only published posts.“ Meta definiert das Feld als eines, das „Indicates whether a scheduled post was published (applies to scheduled Page Post only, for users post and instantly published posts this value is alwaystrue`).“

Dieses Feed-Verhalten erwischt alle, die die Beiträge einer Seite in eine Datenbank synchronisieren. Ein Job, der /feed liest, ohne nach is_published zu fragen, sammelt geplante Beiträge ein, als wären sie live. Frage das Feld immer ab und filtere danach. Wie verschiedene Planungstools das über Netzwerke hinweg abbilden, zeigt der Vergleich von neun Social-Media-Planungs-APIs.

Häufig gestellte Fragen

Wie lang ist die Mindestvorlaufzeit für Facebook scheduled_publish_time?

Zehn Minuten. Der Posts-Leitfaden der Pages API und die Page-Feed-Referenz messen die Untergrenze von 10 Minuten ab dem Zeitpunkt der API-Anfrage, die Page-Videos-Referenz misst sie ab dem Zeitpunkt der Veröffentlichung des Videos, und der Reels-Publishing-Leitfaden verlangt eine Zeit, die mehr als 10 Minuten in der Zukunft liegt. Die Page-Photos-Referenz nennt überhaupt keinen Bereich.

Wie groß ist das maximale Planungsfenster für einen Facebook-Seitenbeitrag über die API?

Meta veröffentlicht für /feed zwei Zahlen. Der Posts-Leitfaden der Pages API sagt 30 Tage, die Page-Feed-Referenz sagt 75 Tage. Für Videos auf /{page-id}/videos sagt die Page-Videos-Referenz 6 Monate, und für Reels auf /{page-id}/video_reels sagt der Reels-Publishing-Leitfaden 29 Tage. Eine Grenze von 30 Tagen für Feed-Beiträge funktioniert, egal welche Seite recht hat.

Muss ich published=false setzen, um scheduled_publish_time zu nutzen?

Ja. Metas Leitfaden macht scheduled_publish_time davon abhängig, dass published auf false steht. Mit dem Standardwert true geht der Beitrag sofort live.

Kann scheduled_publish_time ein ISO-8601-Datumsstring sein?

Der Posts-Leitfaden der Pages API akzeptiert ISO 8601, mit dem Beispiel 2018-09-01T10:15:30+01:00, sowie strtotime()-Strings wie +2 weeks. Die Referenzseiten typisieren das Feld als UNIX-Zeitstempel oder int64, also ist ein Integer in Sekunden die sicherste Wahl.

Welchen Fehler gibt die Graph API für einen scheduled_publish_time außerhalb des Fensters zurück?

Meta dokumentiert keine spezifische Meldung. Die Referenzen zu Page Videos und Page Post nennen Code 100, „Invalid parameter“, als allgemeinen Validierungsfehler. Behandle den Code und protokolliere die Meldung, denn Meta warnt, dass sich Beschreibungstexte ohne Vorankündigung ändern können.

Wie liste ich geplante Beiträge einer Facebook-Seite über die API auf?

Frage /{page-id}/feed ab und fordere das Feld is_published an. Meta liefert an diesem Endpunkt veröffentlichte und unveröffentlichte Beiträge zusammen, und is_published ist false für einen Beitrag, der noch geplant ist.

Muss scheduled_publish_time in Sekunden oder Millisekunden angegeben werden?

In Sekunden. Metas Pages-API-Leitfaden verlangt einen ganzzahligen UNIX-Timestamp in Sekunden. Date.now() in JavaScript liefert Millisekunden, also eine 1.000-mal zu große Zahl. Teile den Wert vor dem Senden durch 1.000.

Verwendet scheduled_publish_time UTC oder meine lokale Zeitzone?

Ein UNIX-Timestamp in Sekunden bezeichnet einen absoluten Zeitpunkt und trägt keine Zeitzone. Meta sagt nicht, nach welcher Uhr oder Zeitzone ein String wie tomorrow geparst wird, also sende besser eine Ganzzahl. Prüfe die Mindestvorlaufzeit von 10 Minuten und deine Obergrenze gegen die Uhr deines Servers in UTC-Sekunden.

Kann ich einen in Meta Business Suite geplanten Beitrag über die API bearbeiten?

Mit einer eigenen App nicht. Laut Pages-API-Leitfaden kann eine App einen Seitenbeitrag nur aktualisieren, wenn er mit dieser App erstellt wurde. Ein in Meta Business Suite geplanter Beitrag lässt sich daher nicht bearbeiten. Beiträge, die deine App erstellt hat, aktualisierst du mit einem POST an /{page_post_id}.

Funktioniert scheduled_publish_time auch bei Facebook Reels?

Ja, mit zwei Unterschieden. Reels laufen über /{page-id}/video_reels, und das Feld nimmt nur einen Unix-Timestamp. Es wird mit video_state=SCHEDULED statt mit published=false kombiniert, und der Reels-Leitfaden verlangt eine Zeit von mehr als 10 Minuten und höchstens 29 Tagen in der Zukunft.