A Meta documenta quatro limites diferentes para o scheduled_publish_time do Facebook

O que é o scheduled_publish_time do Facebook?

O campo scheduled_publish_time do Facebook é o parâmetro da Graph API que diz à Meta quando um post não publicado de uma Página deve entrar no ar, e você o envia no mesmo POST que cria o post. Ele existe em /{page-id}/feed para posts de texto e de link, em /{page-id}/videos para vídeo e em /{page-id}/photos para fotos.

O guia de posts da Pages API da Meta lista o campo como um subitem de published, e essa é a primeira coisa a entender sobre ele: "published set to true to publish the post immediately (default) or false to publish later". Logo abaixo dessa linha: "Include scheduled_publish_time if set to false".

A requisição de exemplo do próprio guia é 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",
  }'

Em caso de sucesso, a resposta é o ID de um post que existe mas ainda não apareceu na Página: {"id": "page_post_id"}. O resto desta página trata das três coisas que decidem se essa requisição funciona: a flag published, o formato do horário e a antecedência.

O scheduled_publish_time exige published=false?

Sim. Um post agendado de Página é um post não publicado com uma data anexada, então os dois parâmetros andam juntos. Deixe published no padrão true e o post sai na hora.

Fotos acrescentam uma etapa. A referência Page Photos diz que uma foto usada em um post agendado precisa ser enviada com temporary=true, e descreve esse parâmetro em uma linha: "published must be false, and you can't set scheduled_publish_time". O agendamento vai no post do feed que anexa as fotos, não nas fotos em si. Para um post com várias fotos, a Meta escreve: "When the photos are part of a scheduled post, the published, scheduled_publish_time, and unpublished_content_type parameters must be included." O exemplo dela envia published=false, scheduled_publish_time=1512068400 e unpublished_content_type=SCHEDULED para /feed.

Envie essas fotos pouco antes de criar o post. A Meta afirma que um upload não publicado "will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them."

Vale conhecer um deslize da referência Page Feed antes de copiar código dela. A tabela de parâmetros chama a flag de published, enquanto a seção "Posting a Link to a Page" manda "Set the publish parameter to 1 to publish the post immediately or to 0 to create an unpublished post to be published later". A requisição de exemplo logo abaixo dessa frase envia published=1. Fique com published.

Quais formatos de horário o scheduled_publish_time aceita?

O guia de posts da Pages API lista três formatos:

O texto do link no guia escreve o padrão como "ISO 8061". O link em si aponta para a ISO 8601, e o exemplo é uma string ISO 8601 válida, então leia como erro de digitação.

As páginas de referência são mais restritas que o guia. A referência Page Feed tipa o parâmetro como timestamp e o chama de "UNIX timestamp indicating when post should go live." As referências Page Photos e Page Videos tipam o campo como int64. Só o guia menciona strings. Um inteiro UNIX em segundos é o único formato que todas as páginas aceitam, então mande esse. O Date.now() do JavaScript devolve milissegundos, o que gera um número 1.000 vezes maior que o certo, então divida antes de enviar.

Se você usar uma string relativa, a Meta diz como conferir o 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 de qual relógio de servidor e qual fuso horário faz o parsing, e a Meta não diz nada sobre nenhum dos dois.

Ler o valor de volta tem sua própria peculiaridade. Na lista de campos da referência Page Feed, o campo de leitura aparece escrito sheduled_publish_time, sem um "c", e tipado como float. A referência Page Post escreve corretamente scheduled_publish_time. Peça a grafia correta.

Com quanta antecedência dá para agendar com o scheduled_publish_time?

No mínimo 10 minutos. O máximo depende de qual página da Meta você lê, e as páginas discordam.

O piso de 10 minutos é o único número em que todas concordam. O piso do Mastodon é a metade disso, e a documentação dele diz isso em uma linha, "Must be at least 5 minutes in the future", que é por que o scheduled_at da API do Mastodon precisa de 5 minutos de folga.

A divergência em /feed é a que mais pesa, porque posts de texto, posts de link e posts agendados com várias fotos passam todos por ele. Duas páginas da Meta dão dois tetos para o mesmo parâmetro no mesmo endpoint: o guia diz 30 dias, a referência diz 75. Nada em nenhuma das duas diz qual está em vigor, e nenhuma menciona o número da outra. Uma ferramenta que permite 75 dias funciona se a referência estiver certa e falha em algum ponto entre o dia 31 e o dia 75 se o guia estiver certo. Uma ferramenta que limita a 30 dias funciona nos dois casos. Limite a 30.

O número dos vídeos também merece uma segunda olhada. As páginas de feed medem a partir de "the time of the API request". A referência de vídeos mede a partir de "the time of publishing the video", o que fica ambíguo para um vídeo cujo upload termina minutos depois da requisição que o iniciou. Deixe uma margem nas duas pontas.

As referências de fotos e vídeos da Meta também listam mais estados não publicados do que explicam. As duas páginas listam valores de unpublished_content_type que incluem SCHEDULED, SCHEDULED_RECURRING, DRAFT e PUBLISH_PENDING, e nenhuma diz o que SCHEDULED_RECURRING faz. Fique com SCHEDULED.

Que erro a Meta devolve quando o horário está fora da janela?

A Meta não publica nenhum. Nenhuma das páginas acima cita uma mensagem de erro para um scheduled_publish_time cedo ou tarde demais. As referências Page Videos e Page Post listam o erro 100, "Invalid parameter", como falha genérica de validação, e é só até aí que a documentação da Meta chega.

Monte o tratamento em torno do código. A própria referência de erros da Marketing API da Meta dá o motivo em uma linha: "Error handling should be done using only the Error Codes. The Description string is subject to change without prior notice." Registre os campos message e fbtrace_id para depuração, mas baseie a lógica de retry em code. O guia de tratamento de erros da Meta descreve o fbtrace_id como "Internal support identifier", que é o valor a passar para o suporte da Meta.

Uma rejeição por janela de horário também não é um erro que vale repetir. Repetir a mesma requisição envia o mesmo timestamp ruim e recebe o mesmo 100. Valide a janela antes da chamada: pelo menos 10 minutos e no máximo 30 dias à frente para /feed, medidos pelo relógio do seu servidor em segundos UTC. O YouTube agenda uploads por outros campos, com outros modos de falha, e cada campo do fluxo de agendamento do YouTube, e como cada um falha, é tratado à parte.

Como alterar ou cancelar um post agendado no Facebook?

Atualize com um POST para /{page_post_id} ou apague com um DELETE no mesmo caminho. Os parâmetros de atualização da referência Page Post incluem scheduled_publish_time e is_published, mas a tabela não dá a nenhum dos dois uma descrição além do próprio nome. O guia da Pages API acrescenta uma restrição: "An app can only update a Page post if the post was made using that app." Por essa regra, um post agendado no Meta Business Suite não é um post que seu app possa editar.

Para encontrar posts agendados, leia /{page-id}/feed com o campo is_published. A referência Page Feed diz isso diretamente: "Published and unpublished posts will be returned when querying the /{page-id}/feed endpoint. Use the 'is_publishedfield to return only published posts." A Meta define o campo como um 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`)."

Esse comportamento do feed pega quem sincroniza os posts de uma Página com um banco de dados. Um job que lê /feed sem pedir is_published coleta posts agendados como se estivessem no ar. Sempre peça o campo e filtre por ele. Para ver como diferentes agendadores expõem isso em várias redes, veja como nove APIs de agendamento de redes sociais se comparam.

Perguntas frequentes

Qual é a antecedência mínima do scheduled_publish_time do Facebook?

Dez minutos. O guia de posts da Pages API e a referência Page Feed medem o piso de 10 minutos a partir do momento da requisição à API, a referência Page Videos mede a partir do momento da publicação do vídeo, e o guia de publicação de Reels exige um horário a mais de 10 minutos à frente. A referência Page Photos não informa nenhum intervalo.

Qual é a janela máxima de agendamento de um post de Página do Facebook pela API?

A Meta publica dois números para /feed. O guia de posts da Pages API diz 30 dias, e a referência Page Feed diz 75 dias. Para vídeos em /{page-id}/videos, a referência Page Videos diz 6 meses, e para Reels em /{page-id}/video_reels o guia de publicação de Reels diz 29 dias. Limitar posts de feed a 30 dias funciona qualquer que seja a página certa.

Preciso definir published=false para usar o scheduled_publish_time?

Sim. O guia da Meta condiciona o scheduled_publish_time a published ser false. Com o padrão true, o post entra no ar na hora.

O scheduled_publish_time pode ser uma string de data ISO 8601?

O guia de posts da Pages API aceita ISO 8601, com o exemplo 2018-09-01T10:15:30+01:00, além de strings de strtotime() como +2 weeks. As páginas de referência tipam o campo como timestamp UNIX ou int64, então um inteiro em segundos é a escolha mais segura.

Que erro a Graph API devolve para um scheduled_publish_time fora da janela?

A Meta não documenta uma mensagem específica. As referências Page Videos e Page Post listam o código 100, "Invalid parameter", como erro genérico de validação. Trate o código e registre a mensagem, já que a Meta avisa que as strings de descrição podem mudar sem aviso.

Como listar os posts agendados de uma Página do Facebook pela API?

Consulte /{page-id}/feed e peça o campo is_published. A Meta devolve posts publicados e não publicados juntos nesse endpoint, e is_published vale false para um post que ainda está agendado.

O scheduled_publish_time vai em segundos ou em milissegundos?

Em segundos. O guia da Pages API da Meta pede um timestamp UNIX inteiro em segundos. O Date.now() do JavaScript devolve milissegundos, um número 1.000 vezes maior, então divida por 1.000 antes de enviar.

O scheduled_publish_time usa UTC ou o meu fuso horário local?

Um timestamp UNIX em segundos marca um momento absoluto, então não carrega fuso horário. A Meta não diz qual relógio ou fuso interpreta uma string como tomorrow, por isso envie um inteiro. Confira o mínimo de 10 minutos e o seu teto pelo relógio do seu servidor, em segundos UTC.

Posso editar pela API um post agendado no Meta Business Suite?

Não com o seu próprio app. O guia da Pages API diz que um app só pode atualizar um post de Página se ele foi criado por esse mesmo app, então um post agendado no Meta Business Suite não pode ser editado. Os posts que o seu app criou são atualizados com um POST para /{page_post_id}.

O scheduled_publish_time funciona com Reels do Facebook?

Funciona, com duas diferenças. Os Reels passam por /{page-id}/video_reels, e o campo aceita apenas um timestamp Unix. Ele vem junto com video_state=SCHEDULED em vez de published=false, e o guia de publicação de Reels exige um horário a mais de 10 minutos e dentro de 29 dias.