Skip to main content
Campanha = o quê (template) + por onde (canais) + para quem (segmento ou IDs). O Run enfileira, não é um motor separado da API de envio.

​
O que é uma campanha?

É o disparo em lote para uma audiência usando um template multicanal. O painel e a API compartilham o mesmo fluxo de fila, créditos e status. Analogia: template é o texto do correio. Segmento é a lista de endereços. Campanha é carimbar e soltar na caixa.

​
Campanha × segmento × envio direto

​
Quando usar?

Funciona muito bem para newsletter, promoção para público filtrado e teste com poucos IDs antes da base inteira. Para um aviso único por script, use envio direto na API do canal ou template.

​
Canais na campanha

channels aceita: whatsapp, sms, email, telegram, push, rcs, instagram. Cada canal listado precisa estar habilitado no template. Sem telefone, e-mail ou peer, o contato é ignorado naquele canal (sem erro por pessoa).
Marketing: contato precisa receiveMarketing e inscrição no tópico do template (quando vinculado). Quem não passa não entra na fila.

​
Se um canal falhar no envio

channelFailureMode define o que acontece quando um canal não pode disparar por problema de infra (domínio de e-mail não verificado, instância WhatsApp/Telegram ausente, etc.). No painel: Se um canal falhar no envio. Na API: channelFailureMode no create/patch. Valores: STRICT (padrão) ou PARTIAL. Com PARTIAL, você pode salvar a campanha mesmo com infra pendente; na hora do Run, o canal só entra na fila se estiver OK. Com STRICT, create/patch já exige domínio de e-mail verificado, remetente WhatsApp em from (instância ou pool) e telegramInstanceId quando o canal está na campanha.

​
Como funciona na prática

  1. Template com canais ativos e texto preenchido
  2. New campaign, nome, template, canais desta execução, audiência (segmento ou IDs)
  3. Roteamento: WhatsApp, Telegram, e-mail conforme tabela acima
  4. Opcional: agendar uma ou mais datas (mín. ~2 min à frente) → Runs SCHEDULED
  5. Preview do segmento (se usar segmento)
  6. Run imediato ou disparo no horário → RUNNING → COMPLETED ou FAILED

​
Rodar de novo (re-disparo)

Você pode executar a mesma campanha mais de uma vez sem editar o rascunho. No diálogo de confirmação do Run: Analogia: a campanha é o modelo do envelope; cada Run é uma nova rodada na fila. Você escolhe quais carteiros (canais) saem desta vez e pode pular quem já recebeu. Na API: GET /v1/campaigns/{id}/run-preview devolve overlap, custo e avisos; POST /v1/campaigns/{id}/run aceita channels[] e excludeAlreadySent. O Run grava os canais efetivos em channelsUsed.

​
Agendar envios

No painel Agendar, as opções de canal e reenvio ficam alinhadas ao Executar: Cada Run agendado persiste channelsOverride (ou todos os canais se omitido/null) e excludeAlreadySent. Na hora H, o scheduler chama o mesmo fluxo do Run com esses valores. Runs já agendados não são editáveis nesses campos — cancele e crie de novo. A lista de próximos envios no painel mostra, de forma compacta, canais e se a exclusão de já enviados está ativa.

​
Status

​
Variáveis globais (opcional)

JSON mesclado por cima dos dados do contato, cupom igual para todos:

​
Na API

O Run devolve sent e runId. Links curtos recebem utm_campaign e utm_content automaticamente.

​
Checklist antes do Run

  1. Canais da campanha ativos no template?
  2. Preview do segmento faz sentido?
  3. Telegram: peers na instância certa?
  4. Testou com poucos IDs?
  5. Créditos, instâncias e remetente de e-mail OK?
Códigos comuns: CAMPAIGN_CHANNEL_NOT_IN_TEMPLATE, CAMPAIGN_AUDIENCE_TOO_LARGE, CAMPAIGN_WHATSAPP_INSTANCE_REQUIRED. Veja Respostas de erro.

​
Próximos passos