Automações

As Automações são o motor reativo da Kiraa. Diferente de uma campanha (que é um lote one-shot), uma automação é um fluxo permanente que observa o que acontece no CRM — cliente entrou numa etapa, recebeu uma tag, agente detectou um intent — e dispara uma régua que combina IA, mensagens, espera, condicionais, ações no próprio CRM e até delegação de tarefa para o time humano. Você define a régua uma vez no construtor visual; cada cliente flui por ela conforme seu comportamento.

Acesse em Operação > Automações. O construtor visual é arrastar e soltar — não precisa código.

Automação vs. Campanha

Os dois conceitos compartilham a malha de envio (voz, e-mail, SMS, WhatsApp), mas resolvem cenários diferentes:

	Campanha	Automação
Disparo	Lote one-shot	Reativo permanente
Origem	Lista importada/segmento	Gatilho de evento
Vida	Termina quando a lista acaba	Vive até você desligar
Por cliente	1 envio agendado	Run com várias etapas
Caso típico	”Mandar promoção pra 5k contatos"	"Quem entrou em ‘Lead’, tenta ligar; se não atende, manda WhatsApp em 2h”

Pergunta-chave: isso vai rodar uma vez para uma lista, ou vai disparar toda vez que algo acontecer? Lote → Campanha. Reativo → Automação.

Anatomia de uma automação

Toda automação tem dois ingredientes:

Gatilho (Trigger)

Define quando a automação começa para um cliente. Cada automação tem 1 gatilho.

Blocos (Steps)

Definem o que acontece depois do gatilho. Vão desde “ligar com IA” até “esperar 2 dias”.

A automação roda como um fluxo: começa no bloco de entrada e segue pelas conexões (edges) até chegar a um bloco terminal (end_run). Cada cliente tem sua própria run — instância isolada do fluxo, com estado e contexto próprios.

Gatilhos disponíveis

Entrada em etapa do pipeline (stage_entry)

Dispara quando um cliente é movido para uma etapa específica do pipeline.Cobre todas as formas de mudança de etapa:

Arrastar no Board
Movimentação em lote (bulk move)
Classificação automática pós-chamada
PATCH via API

Casos típicos: régua de boas-vindas quando entra em “Cadastrado”, régua de cobrança quando entra em “Em atraso D+5”.

Intent detectado pelo agente (intent)

Dispara quando o agente de IA classifica a intenção da conversa.Intents disponíveis: voicemail, wrong_number, not_the_person, customer_not_interested, entre outros.Casos típicos: detectou caixa postal → manda WhatsApp; detectou pessoa errada → move para “verificar contato”.

Tag adicionada (tag_added)

Dispara quando uma tag é adicionada ao cliente — manualmente, por outra automação ou por uma tool do agente (add_client_tag).Casos típicos: tag “lead_quente” inicia régua VIP; tag “inadimplente” inicia régua de cobrança.

Campo customizado alterado (custom_field_changed)

Dispara quando um campo customizado específico muda de valor.Casos típicos: quando valor_proposta é preenchido, manda WhatsApp com link de aceite; quando data_vencimento muda, reagenda a régua de cobrança.

Disparo manual (manual)

Você seleciona clientes na lista do CRM e dispara a automação para eles diretamente.Casos típicos: régua especial para um grupo selecionado, fluxo de teste, recuperação pontual.

Agendado (schedule)

Dispara periodicamente em horários e dias configurados (ex: 09:00 toda seg-sex, America/Sao_Paulo).Modos do schedule:

Cliente — varre clientes elegíveis e cria 1 run por cliente (padrão)
Cobrança (régua) — varre payment_intents elegíveis e cria 1 run por cobrança. Ativado quando você preenche a seção “Cobrança (régua)” do filtro do trigger (status do pagamento, carteira, janela de vencimento).

Casos típicos: régua de cobrança diária (D-5 lembrete, D vence hoje, D+5 ligação, etc.), envio de NPS semanal, limpeza de leads frios.Ver Régua de cobrança abaixo para o caso completo.

Blocos disponíveis

Os blocos se dividem em ações (fazem alguma coisa) e controle (decidem o caminho do fluxo).

Blocos de ação

Bloco	O que faz	Parâmetros principais
Ligar (`call`)	Aciona o agente de voz para ligar para o cliente	Agente, prioridade de telefone, tentativas, duração máxima
Enviar e-mail	Envia e-mail usando um template	Template, integração Gmail (opcional)
Enviar SMS	Envia SMS via Twilio usando um template	Template, integração Twilio (opcional)
Enviar WhatsApp	Envia WhatsApp via UAZAPI usando um template	Template, mídia (opcional), integração
Mover etapa	Move o cliente para outra etapa do pipeline	Etapa de destino, pipeline (cross-pipeline opcional)
Adicionar tag	Adiciona uma tag ao cliente	Tag (string)
Remover tag	Remove uma tag do cliente	Tag (string)
Setar campo customizado	Atualiza valor de um custom field	Campo, valor
Criar tarefa	Cria uma tarefa humana vinculada ao cliente	Título, descrição, responsável, prazo
Gerar cobrança (`generate_payment_intent`)	Materializa PIX ou Boleto via gateway integrado para a cobrança da run	Método (pix/boleto), validade, `reuse_active`
Terminar run (`end_run`)	Marca a run como concluída	—

Blocos de controle

Bloco	O que faz	Notas
Esperar (`wait`)	Pausa a run por um período definido	Pode ser tempo fixo (1s a 30 dias) ou “próximo horário comercial” respeitando timezone
Condicional (`condition`)	Branch if/else baseado em um campo	Operadores: `=`, `≠`, `in`, `contains`, `existe`, `>`, `<`, `≥`, `≤`
Esperar evento externo (`wait_for_event`)	Pausa até receber um webhook ou timeout	Branches: `recebido` / `timeout`
Verificar status do pagamento (`check_payment_status`)	Branch pelo status atual da cobrança da run (Pago / Aguardando / Atrasado / Expirado / Cancelado / Falhou)	Uma saída por status, igual ao board /pagamentos
Verificar janela de cadência (`cadence_check`)	Branch pelo “estado de cadência hoje” — quantos dias faltam ou se passaram do vencimento da parcela	Lista editável de janelas (`from_days`, `to_days`, label)

Toda automação precisa ter pelo menos um caminho que chegue em Terminar run (end_run). Sem isso, a run fica órfã.

Variáveis em parâmetros (templating)

Vários blocos aceitam variáveis no formato {{variavel}}. A resolução acontece nessa ordem:

Atalhos de cliente em PT-BR: {{cliente_nome}}, {{cliente_empresa}}, {{cliente_email}}, {{cliente_telefone}}.
Atalhos em inglês: {{name}}, {{client_name}}, {{company}}, {{email}}, {{phone}}.
Custom fields: {{cpf}} ou {{custom.cpf}} (ambos funcionam).
Contexto da run: {{context.X}} — variáveis que a própria run acumula durante a execução (ex: disposition da call).
Mock values do template: fallback se o cliente não tem o dado.
Se nada resolve, vira string vazia (sem {{undefined}} no output).

É um sintaxe simples — não tem condicionais inline ou loops como Jinja2 completo. Para lógica complexa, use o bloco Condicional no fluxo.

Construtor visual

A página de uma automação tem três áreas principais:

Paleta de blocos

Sidebar esquerda com todos os blocos disponíveis. Arraste para o canvas.

Canvas

Centro da tela. Conecte blocos arrastando das alças. Zoom, pan, undo/redo.

Painel de configuração

Sidebar direita. Aparece quando você clica em um bloco. Formulário muda conforme o tipo.

Como criar uma automação

Nova automação

Em Operação > Automações, clique em Nova automação.

Escolha o gatilho

Selecione um dos 5 gatilhos disponíveis. Cada gatilho pede configurações específicas (ex: stage_entry pede pipeline + etapa).

Monte o fluxo

Arraste blocos da paleta para o canvas. Conecte-os arrastando das alças (handles). O bloco de entrada é destacado.

Configure cada bloco

Clique em um bloco para abrir o painel de configuração. Preencha os parâmetros (template, etapa, prazo, etc.).

Defina a janela de execução (opcional)

Em Configurações da automação você define dias/horários permitidos respeitando o timezone da sua organização.

Ative

Volte para a lista, ative a automação e ela passa a reagir aos gatilhos em tempo real.

Edições no fluxo geram uma nova versão da automação. Runs em andamento ficam fixadas na versão antiga até terminarem — você não corrompe estado de clientes que já estão executando.

Acompanhando execuções (aba Runs)

Cada automação tem uma aba Runs que lista todas as instâncias em execução ou histórico, com:

Cliente (com link para a ficha)
Status atual: waiting, running, in_call, completed, failed, cancelled
Bloco atual (em qual passo a run está parada)
Histórico expandido (cada step executado, com input/output)

Use a aba Runs para depurar fluxos: confirmar que o gatilho disparou, ver onde a run travou, conferir o que o agente detectou (disposition da call), etc.

Quando uma run cai em failed, o motivo aparece no histórico. Erros comuns: integração desconectada, template inativo, etapa de destino removida.

Casos de uso completos

Caso 1 — Re-engajamento de leads frios (B2B)

Gatilho: tag “lead_frio” adicionada

├─ Enviar WhatsApp (template "estamos voltando")
├─ Esperar 2 dias
├─ Condicional (custom_field "respondeu_whatsapp" existe?)
│  ├─ true → end_run
│  └─ false → Ligar (agente "Reengajamento")
│             └─ Condicional (intent == "wrong_number")
│                ├─ true → Mover etapa "Telefone errado" + end_run
│                └─ false → Esperar 7 dias → end_run

Resultado: o lead que abandonou recebe WhatsApp; se não responde, recebe ligação; se a IA detecta telefone errado, é tirado do funil sem desperdiçar mais tentativas.

Caso 2 — Régua de cobrança (daily-decision)

Gatilho: Schedule 09:00 seg-sex, filtro de cobrança: pending + overdue, carteira BCSUL

Trigger schedule (1 run por cobrança elegível)
│
├─ check_payment_status
│  ├─ paid → end_run
│  ├─ pending_generation → generate_payment_intent (PIX) ─┐
│  └─ pending / overdue ──────────────────────────────────┤
│                                                         ▼
│                                              cadence_check (delta)
│                                                         │
│            ┌─ janela "Pré-aviso (-5 a -1d)" → Enviar WhatsApp (lembrete amigável)
│            ├─ janela "Vence hoje (0)"       → Enviar WhatsApp (vence hoje)
│            ├─ janela "Atraso 1-5d"          → Enviar WhatsApp (atraso inicial)
│            ├─ janela "Atraso 6-15d"         → Enviar WhatsApp (oferta de acordo)
│            └─ janela "Atraso >15d"          → Ligar (agente Cobrança)
│                                                  ├─ disposition = promessa_pagamento → Criar tarefa
│                                                  └─ default → end_run

Resultado: a régua roda todo dia decidindo o canal certo para cada cobrança. Quando o devedor paga, o webhook cancela a run; quando assina acordo, idem. Sem wait Xd segurando estado.

Caso 3 — Cross-channel com fallback (vendas)

Gatilho: entrada na etapa “Lead qualificado”

├─ Ligar (agente "Vendas")
├─ Condicional (disposition == "voicemail")
│  ├─ true → Enviar WhatsApp (template "tentei te ligar...")
│  │        Esperar 4h
│  │        Ligar (segunda tentativa)
│  │        Condicional (disposition == "voicemail")
│  │           ├─ true → Enviar e-mail "vamos marcar?" + end_run
│  │           └─ false → ... (atendeu)
│  └─ false → ... (atendeu — segue conversão)

Resultado: a régua tenta voz, mas se cair em caixa postal troca para WhatsApp e tenta de novo, e só aciona e-mail como último recurso.

Caso 4 — Onboarding com confirmação humana (clínica)

Gatilho: entrada na etapa “Cadastrado”

├─ Enviar WhatsApp (template "boas-vindas")
├─ Ligar (agente "Recepção" — agenda primeira consulta)
├─ Esperar evento externo (event_type="primeira_consulta_realizada", timeout=30 dias)
│  ├─ recebido → Mover etapa "Cliente ativo" + end_run
│  └─ timeout → Criar tarefa ("Cliente não voltou — investigar")
│              + end_run

Resultado: paciente é onboardado pela IA; se não comparece à consulta em 30 dias, vira tarefa para a coordenadora investigar.

Capacidades não-óbvias

Cascata de gatilhos

O bloco Mover etapa pode disparar outra automação que escuta stage_entry. Permite encadear automações sem ramificar tudo numa só.

Contexto como state machine

A run acumula variáveis ao longo do fluxo. O disposition da call (voicemail, wrong_number) fica em context e o Condicional lê de lá — sem precisar consultar o banco.

Loops com espera

O detector de ciclos permite loops que passam por Esperar. Ex: “tenta ligar; se não atende, espera 2h; tenta de novo (até 3x)” é um loop válido.

Soft-fail em delegação

Se o bloco Criar tarefa não consegue resolver responsável, marca o step como skipped (não falha — o run continua). Workflow não para por delegação sem dono.

Régua de cobrança

A régua de cobrança é uma especialização do motor de Automações: um workflow agendado que tem como eixo cada cobrança específica (payment_intent) — não o cliente. Todo dia, pra cada cobrança em aberto, decide o que fazer hoje com base em quantos dias faltam (ou se passaram) do vencimento.

Gera o PIX se preciso, manda mensagem da cadência certa, escala pra ligação se atrasou demais, encerra sozinha quando o dinheiro cai.

A grande ideia: 1 run por cobrança

Workflows comuns rodam 1 run por cliente. A régua roda 1 run por cobrança — se o cliente João tem 3 cobranças vencidas, a régua cria 3 runs paralelas. Isso permite que templates digam "Sua cobrança de {{pagamento_valor}} vence em {{parcela_vencimento}}" sem precisar lógica extra: a run já sabe qual é a dela.

Como ativar o modo régua

Crie uma automação com trigger = Schedule (ex: 09:00 toda seg-sex). No filtro do trigger, ative a seção “Cobrança (régua)”:

+------------------------------------------+
| Cobrança (régua)                         |
| Régua ativa: 1 run por cobrança elegível |
|                                          |
| Status do pagamento                      |
| [x] Aguardando geração                   |
| [x] Aguardando pagamento                 |
| [x] Atrasado                             |
| [ ] Pago    [ ] Expirado                 |
| [ ] Cancelado    [ ] Falhou              |
|                                          |
| Carteira  [Qualquer carteira  v]         |
|                                          |
| > Janela de vencimento (opcional)        |
+------------------------------------------+

Quando qualquer campo dessa seção tem valor, o engine entende que é uma régua e ativa o fan-out por cobrança (em vez de por cliente). Os chips de status são os mesmos da página Cobrança → Pagamentos — incluindo Atrasado virtual.

Usar a régua padrão (preset)

Se o canvas está vazio numa automação de cobrança, aparece o botão flutuante “Usar régua padrão”. Ele monta o grafo canônico em 1 clique:

                  +--------------+
                  | GEN (PIX)    |
                  | generate_pi  |
                  +------+-------+
                         |
   +------------+        v               +---------------+
   |  ENTRY     |---> CADENCE --janela--> SEND_PRE      -+
   | check_pay- | pen-    |          1   (5-1d antes)    |
   | ment_status| ding    +--janela 2---> SEND_DUE      -+
   |            | overdue              (vence hoje)      |
   | paid ------+                                        |
   | pending_gen --> GEN |             +--> SEND_DAILY  -+--> END
   | expired/   |        +--janela 3 --| (1-5d atraso)   |
   | cancel/    |        +--janela 4 ----> SEND_REDUC   -+
   | failed     |                       (6-15d atraso)   |
   +------------+        +--janela 5 ----> CALL          -+
                                          (>15d atraso)

Tradução em palavras:

ENTRY (check_payment_status) roteia pelo estado atual: paid → END, pending_generation → passa por GEN, pending/overdue → direto pro CADENCE.
GEN (generate_payment_intent) materializa PIX/Boleto se ainda não existe. Salva link_pagamento, qr_code_pix, valor_atualizado no contexto.
CADENCE (cadence_check) é o coração: calcula delta = hoje - vencimento e escolhe a primeira janela cujo intervalo [from_days, to_days] cobre o delta.
SEND_* / CALL é a ação do dia. Cada uma termina em END.
END — amanhã o schedule cria run nova e reavalia em qual janela a cobrança está.

Os blocos send_whatsapp da régua padrão nascem sem template selecionado — clique em cada um e escolha pelo painel de configuração antes de ativar.

Por que daily-decision (e não `wait Xd`)

Cada execução = decisão de um dia. Sem wait segurando run dormente entre envios — quem dita a cadência é o schedule + cadence_check.
Editar a cadência sem migrar runs. Mudou as janelas? A próxima execução cria run nova já com o novo grafo. Não precisa cancelar runs antigas em wait.
Cadência por janela é trivial. “Manda WhatsApp todo dia entre 1 e 5 de atraso” vira UMA janela ligada a UM send_whatsapp.

Idempotência por dia

Se o schedule tem múltiplos horários (["09:00", "15:00"]) ou se alguém dispara execução manual, antes de cada send_* o sistema confere dunning_state.last_sent_per_channel[channel]. Se o último envio do mesmo canal foi há menos de 18h (configurável por step), o step retorna skipped com motivo already_sent_recently. Para forçar reenvio no mesmo dia, defina min_interval_seconds: 0 no step específico.

`cadence_check` — convenção do delta

delta < 0  →  falta vencer    (ex: -5 = vence em 5 dias)
delta == 0 →  vence hoje
delta > 0  →  atrasado em N dias

Configuração default:

{
  "windows": [
    { "id": "pre_aviso",      "label": "Pré-aviso (5-1 dias)",  "from_days": -5, "to_days": -1 },
    { "id": "vence_hoje",     "label": "Vence hoje",            "from_days": 0,  "to_days": 0  },
    { "id": "atraso_inicial", "label": "Atraso 1-5 dias",       "from_days": 1,  "to_days": 5  },
    { "id": "atraso_medio",   "label": "Atraso 6-15 dias",      "from_days": 6,  "to_days": 15 },
    { "id": "atraso_pos15",   "label": "Atraso >15 dias",       "from_days": 16, "to_days": 90 }
  ]
}

Cada janela é uma saída independente no canvas — arraste de qualquer uma para conectar a uma ação diferente.

Cancelamento automático

A run não precisa “ficar de olho” se a cobrança foi paga — ela é cancelada de fora:

Webhook de pagamento confirmado → marca intent paid → cancela toda run ativa daquele intent
Acordo assinado → parcelas viram em_acordo, intents pendentes viram superseded, runs canceladas em batch

Dedupe

Só pode haver uma run ativa por cobrança ao mesmo tempo. Se o tick das 09:00 cria a run, e às 15:00 a run ainda está viva, o sistema não duplica. Só cria outra quando a run anterior termina.

Limites

Fan-out de até 500 intents por tick por automação. Se sobrar, o tick seguinte pega (idempotente via dedupe).
Pre-vencimento via filtro do trigger: para economizar fan-out em carteiras grandes, restrinja com days_to_due_min / days_to_due_max no filtro (ex: -5 a 90).

Variáveis de cobrança em templates

Ver Cobrança → Variáveis disponíveis em templates — a régua popula {{pagamento_valor}}, {{link_pagamento}}, {{pagamento_dias_atraso}}, {{pagamento_lembretes_enviados}}, entre outras.

Limitações conhecidas

Condicional sem AND/OR aninhado — para lógica composta, encadeie múltiplos blocos Condicional.
Sem analytics agregada por automação ainda — você acompanha por run individual na aba Runs.
Pickers do construtor pedem UUID em alguns campos (template, agente, etapa) — copie do contexto do CRM.
Bloco Ligar não retém crédito antecipado — esteja atento ao saldo da organização ao disparar fluxos com volume alto.

Como o sistema executa por trás

Para quem quer entender a engine:

Tick a cada 15 segundos processa runs prontas (até 50 por tick).
Multi-worker safe: runs travadas com FOR UPDATE SKIP LOCKED — múltiplos workers não pegam a mesma run.
Idempotência: a automação não cria run nova se já existe uma ativa para o mesmo (automation_id, client_id).
Janela de execução: respeita dias/horários configurados; fora da janela, reagenda para o próximo slot válido sem executar.
Cap de segurança: run que executa mais de 100 steps cai em failed (step_limit_exceeded).
Estado assíncrono: o bloco Ligar não bloqueia o tick — quando o agente desliga, a run reativa no próximo ciclo.

Próximos passos

Cobrança

Módulo de recebíveis — carteiras, contratos, pagamentos, acordos. Onde a régua opera.

Tarefas

Trabalho humano delegado pelo agente IA ou pelo bloco Criar tarefa

Retornos

Callbacks agendados pelo agente durante a conversa (cross-channel)

Board e Pipelines

Configure etapas com descrição clara para o gatilho stage_entry

Tools (CRM Action)

add_client_tag, move_to_stage, set_custom_field cascateiam automações

​Automação vs. Campanha

​Anatomia de uma automação

Gatilho (Trigger)

Blocos (Steps)

​Gatilhos disponíveis

​Blocos disponíveis

​Blocos de ação

​Blocos de controle

​Variáveis em parâmetros (templating)

​Construtor visual

Paleta de blocos

Canvas

Painel de configuração

​Como criar uma automação

​Acompanhando execuções (aba Runs)

​Casos de uso completos

​Capacidades não-óbvias

Cascata de gatilhos

Contexto como state machine

Loops com espera

Soft-fail em delegação

​Régua de cobrança

​A grande ideia: 1 run por cobrança

​Como ativar o modo régua

​Usar a régua padrão (preset)

​Por que daily-decision (e não wait Xd)

​Idempotência por dia

​cadence_check — convenção do delta

​Cancelamento automático

​Dedupe

​Limites

​Variáveis de cobrança em templates

​Limitações conhecidas

​Como o sistema executa por trás

​Próximos passos

Cobrança

Tarefas

Retornos

Board e Pipelines

Tools (CRM Action)

Automação vs. Campanha

Anatomia de uma automação

Gatilhos disponíveis

Blocos disponíveis

Blocos de ação

Blocos de controle

Variáveis em parâmetros (templating)

Construtor visual

Como criar uma automação

Acompanhando execuções (aba Runs)

Casos de uso completos

Capacidades não-óbvias

Régua de cobrança

A grande ideia: 1 run por cobrança

Como ativar o modo régua

Usar a régua padrão (preset)

Por que daily-decision (e não `wait Xd`)

Idempotência por dia

`cadence_check` — convenção do delta

Cancelamento automático

Dedupe

Limites

Variáveis de cobrança em templates

Limitações conhecidas

Como o sistema executa por trás

Próximos passos