Criar um broadcast

Precisa de um token com broadcasts:write, e de flows:read para escolher o fluxo. Um broadcast chega a leads reais: confirme o público e o horário antes de enviar e prefira agendar, para ainda poder cancelar.

Passo a passo

# 1. um fluxo publicado do provedor certo
curl -s "$API/v1/schemas?status=1" -H "Authorization: Bearer $CF"
# 2. agende (horário local da página) para duas páginas
curl -s -X POST "$API/v1/broadcasts" -H "Authorization: Bearer $CF" -H "Content-Type: application/json" -d '{
  "schemaId": "<id do fluxo publicado>",
  "pageIds": ["<id da página 1>", "<id da página 2>"],
  "type": 5,
  "notificationType": 1,
  "recencyFilter": 0,
  "scheduledTo": "2026-10-01T09:00:00"
}'
# 3. acompanhe
curl -s "$API/v1/broadcasts/<broadcastId>" -H "Authorization: Bearer $CF"
curl -s "$API/v1/broadcasts/<broadcastId>/executions?limit=50" -H "Authorization: Bearer $CF"

Confira skippedPageIds na resposta: páginas que não são suas, ou que foram excluídas, ficam de fora. Um POST /v1/broadcasts não é idempotente: se der timeout, liste /v1/broadcasts?search=&dateFrom= antes de tentar de novo, ou você envia duas vezes.

Regras validadas pela API

• schemaId precisa estar publicado (400 "Schema is not published"). pageIds não pode ser vazio, e as páginas precisam ser do mesmo provedor do fluxo.
• type: em páginas da Meta prefira 5 (Automático): o sistema tenta, lead a lead, os canais que conseguem entregar (template de utilidade, depois tag de mensagem, depois a janela padrão de 24h). 1 (Padrão) só alcança quem escreveu nas últimas 24h. 3 (Tag de mensagem) exige messageTag e respeito à política da Meta. 4 (Template de utilidade) exige templates aprovados no fluxo. 6 (Todos) é só para Telegram.
• O filtro de recência (recencyFilter diferente de 0) só vale para os tipos 3, 4 e 5. O valor 5 (Personalizado) exige recencyOlderThanHours ou recencyNewerThanHours, cada um entre 1 e 2160 horas.
• scheduledTo é o horário local de cada página (timeZone). Um broadcast para páginas em fusos diferentes gera uma execução por fuso. Omita o campo, ou envie isImmediate: true, para enviar agora.
• tags com tagMatchMode (1 qualquer, 2 todas) filtram o público pelas tags do lead.
• Leads descadastrados e bloqueados sempre ficam de fora.
• POST /v1/broadcasts/delivery-preview (broadcasts:read) estima, antes do envio, como as regras de entrega vão tratar o público das páginas.

Acompanhar e controlar

Método	Rota	Observação
GET	/v1/broadcasts/{broadcastId}	Resumo: status, type, scheduledTo, totalPages, executionSummary, metricsSummary, pages.
GET	/v1/broadcasts/{broadcastId}/executions	Uma linha por página: status, total, successCount, failureCount, pendingCount, sent, errorCount, topError, isBlocked, blockedReason.
GET	/v1/broadcasts	Lista, com total e categoryCounts.
GET	/v1/broadcasts/overview?days=7	Totais de broadcasts, execuções e leads.
PATCH	/v1/broadcasts/{broadcastId}	Altera um broadcast em espera ou pausado; envie só o que muda.
POST	/v1/broadcasts/{broadcastId}/cancel	400 quando já concluído, falho ou cancelado.
POST	/v1/broadcasts/{broadcastId}/executions/{executionId}/cancel e /reprocess	Controle por página. Reprocessar só vale para execuções com falha nas últimas 24h (409 fora disso).
GET	/v1/schemas/{schemaId}/metrics?broadcastId=	Enviados, entregues, lidos, cliques e erros por nó do fluxo naquele broadcast.

A entrega é assíncrona: a execução passa por PendingSegmentation, Processing e Completed. Os leads saem em lotes e o envio respeita o limite de taxa da Meta por página (erro 613), com novas tentativas por até 24h. Para públicos grandes, o status muda ao longo de minutos ou horas: consultar a cada 30 a 60 segundos basta.