Meta documenta cuatro límites distintos para scheduled_publish_time de Facebook

¿Qué es scheduled_publish_time de Facebook?

El campo scheduled_publish_time de Facebook es el parámetro de la Graph API que le dice a Meta cuándo debe publicarse un post de Página no publicado, y se envía en el mismo POST que crea el post. Existe en /{page-id}/feed para posts de texto y de enlace, en /{page-id}/videos para vídeo y en /{page-id}/photos para fotos.

La guía de posts de la Pages API de Meta lo lista como un subelemento de published, y eso es lo primero que hay que entender de él: "published set to true to publish the post immediately (default) or false to publish later". Justo debajo de esa línea: "Include scheduled_publish_time if set to false".

La petición de ejemplo de la propia guía es esta:

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",
  }'

Si todo va bien, la respuesta es el ID de un post que existe pero que todavía no ha aparecido en la Página: {"id": "page_post_id"}. El resto de esta página cubre las tres cosas que deciden si esa petición funciona: el flag published, el formato de la hora y la antelación.

¿scheduled_publish_time requiere published=false?

Sí. Un post de Página programado es un post no publicado con una fecha adjunta, así que los dos parámetros viajan juntos. Si dejas published en su valor por defecto, true, el post sale de inmediato.

Las fotos añaden un paso. La referencia de Page Photos dice que una foto usada en un post programado debe subirse con temporary=true, y describe ese parámetro en una línea: "published must be false, and you can't set scheduled_publish_time". La programación va en el post del feed que adjunta las fotos, no en las fotos. Para un post con varias fotos, Meta escribe: "When the photos are part of a scheduled post, the published, scheduled_publish_time, and unpublished_content_type parameters must be included." Su ejemplo envía published=false, scheduled_publish_time=1512068400 y unpublished_content_type=SCHEDULED a /feed.

Sube esas fotos poco antes de crear el post. Meta indica que una subida no publicada "will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them."

Hay un desliz en la referencia de Page Feed que conviene conocer antes de copiar código de ella. Su tabla de parámetros llama al flag published, mientras que su sección "Posting a Link to a Page" te dice "Set the publish parameter to 1 to publish the post immediately or to 0 to create an unpublished post to be published later". La petición de ejemplo que va debajo de esa frase envía published=1. Quédate con published.

¿Qué formatos de hora acepta scheduled_publish_time?

La guía de posts de la Pages API lista tres formatos:

El texto del enlace de la guía escribe el estándar como "ISO 8061". El enlace en sí apunta a ISO 8601, y el ejemplo es una cadena ISO 8601 válida, así que tómalo como una errata.

Las páginas de referencia son más estrictas que la guía. La referencia de Page Feed tipa el parámetro como timestamp y lo llama "UNIX timestamp indicating when post should go live." Las referencias de Page Photos y Page Videos lo tipan como int64. Solo la guía menciona cadenas. Un entero UNIX en segundos es el único formato que aceptan todas las páginas, así que envía ese. Date.now() de JavaScript devuelve milisegundos, lo que da un número 1,000 veces más grande de la cuenta, así que divide antes de enviarlo.

Si usas una cadena relativa, Meta te dice cómo comprobar el resultado: "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 depende del reloj de servidor y de la zona horaria que lo interpreten, y Meta no dice nada de ninguno de los dos.

Leer el valor de vuelta tiene su propia rareza. En la lista de campos de la referencia de Page Feed, el campo de lectura se escribe sheduled_publish_time, sin una "c", y está tipado como float. La referencia de Page Post lo escribe bien, scheduled_publish_time. Pide la grafía correcta.

¿Con cuánta antelación puedes programar con scheduled_publish_time?

Con al menos 10 minutos. El máximo depende de qué página de Meta leas, y las páginas no coinciden.

El suelo de 10 minutos es la única cifra en la que coinciden todas. El suelo de Mastodon es la mitad, y su documentación lo dice en una línea, "Must be at least 5 minutes in the future", que es por qué el scheduled_at de la API de Mastodon necesita 5 minutos de margen.

La discrepancia en /feed es la que más importa, porque los posts de texto, los de enlace y los posts programados con varias fotos pasan todos por ahí. Dos páginas de Meta dan dos techos para el mismo parámetro en el mismo endpoint: la guía dice 30 días y la referencia dice 75. Ninguna de las dos dice cuál está vigente, y ninguna menciona la cifra de la otra. Una herramienta que permita 75 días funcionará si la referencia tiene razón y fallará en algún punto entre el día 31 y el día 75 si la tiene la guía. Una herramienta que limite a 30 días funciona en los dos casos. Limita a 30.

La cifra de vídeo también merece una segunda mirada. Las páginas del feed miden desde "the time of the API request". La referencia de vídeo mide desde "the time of publishing the video", algo ambiguo para un vídeo cuya subida termina minutos después de la petición que la inició. Deja margen en los dos extremos.

Las referencias de fotos y de vídeos de Meta también listan más estados no publicados de los que explican. Las dos páginas incluyen valores de unpublished_content_type como SCHEDULED, SCHEDULED_RECURRING, DRAFT y PUBLISH_PENDING, y ninguna dice qué hace SCHEDULED_RECURRING. Quédate con SCHEDULED.

¿Qué error devuelve Meta cuando la hora está fuera de rango?

Meta no publica ninguno. Ninguna de las páginas anteriores cita un mensaje de error para un scheduled_publish_time demasiado pronto o demasiado tarde. Las referencias de Page Videos y Page Post listan el error 100, "Invalid parameter", como su fallo de validación genérico, y la documentación de Meta no llega a ser más concreta que eso.

Construye tu gestión de errores alrededor del código. La propia referencia de errores de la Marketing API de Meta da el motivo en una línea: "Error handling should be done using only the Error Codes. The Description string is subject to change without prior notice." Registra los campos message y fbtrace_id para depurar, pero basa la lógica de reintentos en code. La guía de gestión de errores de Meta describe fbtrace_id como un "Internal support identifier", que es el valor que hay que dar al soporte de Meta.

Un rechazo por la ventana de tiempo tampoco es un error reintentable. Reintentar la misma petición envía la misma marca de tiempo errónea y recibe el mismo 100. Valida la ventana antes de la llamada: al menos 10 minutos y como mucho 30 días por delante para /feed, medidos con el reloj de tu servidor en segundos UTC. YouTube programa las subidas con otros campos y otros modos de fallo, y cada campo del flujo de programación de YouTube, y cómo falla cada uno, se cubre aparte.

¿Cómo cambias o cancelas un post programado de Facebook?

Actualízalo con un POST a /{page_post_id}, o bórralo con un DELETE a la misma ruta. Los parámetros de actualización de la referencia de Page Post incluyen scheduled_publish_time e is_published, pero la tabla no da a ninguno una descripción más allá de su propio nombre. La guía de la Pages API añade una restricción: "An app can only update a Page post if the post was made using that app." Según esa regla, un post programado en Meta Business Suite no es uno que tu app pueda editar.

Para encontrar los posts programados, lee /{page-id}/feed con el campo is_published. La referencia de Page Feed lo dice sin rodeos: "Published and unpublished posts will be returned when querying the /{page-id}/feed endpoint. Use the 'is_publishedfield to return only published posts." Meta define el campo como uno que "Indicates whether a scheduled post was published (applies to scheduled Page Post only, for users post and instantly published posts this value is alwaystrue`)."

Ese comportamiento del feed pilla a quien sincroniza los posts de una Página con una base de datos. Un proceso que lee /feed sin pedir is_published recoge los posts programados como si ya estuvieran publicados. Pide siempre el campo y filtra por él. Para ver cómo exponen esto distintos programadores en varias redes, consulta cómo se comparan nueve APIs de programación de redes sociales.

Preguntas frecuentes

¿Cuál es la antelación mínima de scheduled_publish_time de Facebook?

Diez minutos. La guía de posts de la Pages API y la referencia de Page Feed miden el suelo de 10 minutos desde el momento de la petición a la API, la referencia de Page Videos lo mide desde el momento de publicar el vídeo, y la guía de publicación de Reels exige una hora a más de 10 minutos. La referencia de Page Photos no indica ningún rango.

¿Cuál es la ventana máxima de programación de un post de Página de Facebook a través de la API?

Meta publica dos cifras para /feed. La guía de posts de la Pages API dice 30 días, y la referencia de Page Feed dice 75 días. Para vídeos en /{page-id}/videos, la referencia de Page Videos dice 6 meses, y para Reels en /{page-id}/video_reels la guía de publicación de Reels dice 29 días. Limitar los posts del feed a 30 días funciona sea cual sea la página correcta.

¿Tengo que poner published=false para usar scheduled_publish_time?

Sí. La guía de Meta hace que scheduled_publish_time dependa de que published sea false. Con el valor por defecto, true, el post se publica de inmediato.

¿Puede scheduled_publish_time ser una cadena de fecha ISO 8601?

La guía de posts de la Pages API acepta ISO 8601, con el ejemplo 2018-09-01T10:15:30+01:00, además de cadenas de strtotime() como +2 weeks. Las páginas de referencia tipan el campo como marca de tiempo UNIX o como int64, así que un entero en segundos es la opción más segura.

¿Qué error devuelve la Graph API para un scheduled_publish_time fuera de la ventana?

Meta no documenta un mensaje específico. Las referencias de Page Videos y Page Post listan el código 100, "Invalid parameter", como su error de validación genérico. Gestiona el código y registra el mensaje, ya que Meta avisa de que los textos de descripción pueden cambiar sin previo aviso.

¿Cómo listo los posts programados de una Página de Facebook a través de la API?

Consulta /{page-id}/feed y pide el campo is_published. Meta devuelve juntos los posts publicados y los no publicados en ese endpoint, y is_published es false para un post que sigue programado.

¿scheduled_publish_time va en segundos o en milisegundos?

En segundos. La guía de la Pages API de Meta pide un timestamp UNIX entero en segundos. Date.now() de JavaScript devuelve milisegundos, un número 1.000 veces mayor, así que divídelo entre 1.000 antes de enviarlo.

¿scheduled_publish_time usa UTC o mi zona horaria local?

Un timestamp UNIX en segundos marca un momento absoluto, así que no lleva zona horaria. Meta no dice qué reloj o zona horaria interpreta una cadena como tomorrow, por eso conviene enviar un entero. Comprueba el mínimo de 10 minutos y tu tope contra el reloj de tu servidor en segundos UTC.

¿Puedo editar por la API un post programado en Meta Business Suite?

No con tu propia app. La guía de la Pages API dice que una app solo puede actualizar un post de Página si se creó con esa misma app, así que un post programado en Meta Business Suite no se puede editar. Los posts que creó tu app se actualizan con un POST a /{page_post_id}.

¿scheduled_publish_time funciona con los Reels de Facebook?

Sí, con dos diferencias. Los Reels pasan por /{page-id}/video_reels, y el campo solo acepta un timestamp Unix. Se combina con video_state=SCHEDULED en lugar de published=false, y la guía de publicación de Reels exige una hora a más de 10 minutos y dentro de 29 días.