Workflows: gatilhos e ações

Workflows automatizam ações no Codewo. A lógica é simples: quando algo acontece (gatilho), faça algo (ação). Editor visual com nodes conectáveis, condições e ramificações que podem usar análise da IA.

O que é

Workflow é um fluxograma: caixinhas (nodes) conectadas por setas. Um node de gatilho dispara o workflow; nodes de ação executam tarefas; nodes de controle decidem caminhos.

Exemplos do que dá pra automatizar:

• Quando chega mensagem do canal WhatsApp depois das 18h → responder "estamos fora do horário".
• Quando contato é criado com tag "Lead-Quente" → adicionar a um pipeline de vendas.
• Quando conversa fica 15 minutos sem resposta → notificar o gerente.
• Quando email contém a palavra "cancelar" → atribuir pro time de retenção.

Tipos de node

Gatilhos (13 disponíveis)

Gatilho	Quando dispara
Conversa aberta	Conversa nova criada
Conversa fechada	Status muda pra Fechada
Conversa atualizada	Qualquer mudança em campos da conversa
Mensagem recebida	Cliente enviou mensagem
Mensagem enviada	Atendente enviou mensagem
Contato criado	Contato novo cadastrado
Campo do contato atualizado	Qualquer campo do contato muda
Tag do contato atualizada	Tag adicionada ou removida
Contato adicionado a pipeline	Card criado em workspace CRM
Estágio do pipeline mudou	Card mudou de coluna
Arquivo recebido	Anexo entrou pelo canal
Webhook	URL externa chama o Codewo
Atalho/Manual	Disparado manualmente por outro workflow ou por usuário

Ações (18 disponíveis)

Mensagens e email:

• Enviar mensagem (texto/template)
• Fazer pergunta (esperar resposta)
• Enviar email

Contato:

• Atribuir a (membro/equipe/agente IA)
• Adicionar/remover tag
• Atualizar campo do contato

Conversa:

• Abrir/fechar conversa
• Soneca (adiar)
• Adicionar comentário interno
• Atualizar campo da conversa

Fluxo:

• Esperar (delay)
• Esperar resposta do cliente
• Fazer requisição HTTP (chamar API externa)
• Disparar outro workflow
• Enviar notificação

Pipeline:

• Adicionar contato a pipeline
• Mudar estágio do contato no pipeline

IA:

• Disparar agente de IA pra responder
• Gerar resposta sugerida
• Resumir conversa

Controle de fluxo

• Condição — Se X, vai por A; senão por B. Veja a tabela abaixo de campos comparáveis.
• Por canal — Ramifica conforme o canal da conversa.
• Por horário comercial — Dentro ou fora do expediente.
• Branches com IA — Bifurca conforme sentimento, urgência, temperatura do lead, intenção, categoria, complexidade, emoção, ou "smart route" (roteamento inteligente).
• Pular pra — Vai pra outro node específico (útil em loops).
• Fim — Encerra o workflow.

Campos disponíveis em "Condição" (branch)

Quando você adiciona uma Condição, ela compara um campo do contexto da execução. Os campos prontos pra uso:

Sobre o contato:

Campo	O que é
contact.name	Nome do contato
contact.email	Email
contact.phone	Telefone
contact.status	Ativo / Inativo / Bloqueado
contact.tags	Etiquetas
attribution.last.source	Origem do último toque (meta_ads, google_ads, meta_organic, direct, etc.)
attribution.last.campaign	Nome da campanha (utm_campaign)
attribution.last.medium	cpc, organic, email, social
attribution.last.channel_type	Canal de origem

Sobre a conversa:

Campo	O que é
conversation.channel_type	whatsapp, telegram, email, webchat, etc.
conversation.status	open, pending, in_progress, resolved, snoozed, spam
conversation.priority	low, medium, high, urgent
conversation.message_count	Total de mensagens
conversation.first_response_time	Segundos até primeira resposta
conversation.assigned_to_id	ID do atendente
conversation.is_within_business_hours	1 ou 0
conversation.ai_sentiment	positive, neutral, negative
conversation.ai_intent	buy, cancel, support, question, complaint
conversation.ai_urgency_score	0–100
conversation.ai_category	financial, technical, commercial, support

Sobre a mensagem (em triggers de mensagem):

Campo	O que é
message.content	Texto da mensagem
message.content_type	text, image, audio, video, file, template
message.has_attachment	1 ou 0
message.sender_type	contact, agent, bot, workflow

Sobre pipeline/estágio (em triggers de pipeline):

Campo	O que é
pipeline.id	Pipeline específico
stage.key	Estágio canônico (new, qualifying, won, lost, etc.)

Operadores disponíveis

• equals / not_equals — É igual / não é igual (case-sensitive)
• contains / not_contains — Contém / não contém (case-insensitive, funciona com texto e arrays como tags)
• starts_with / ends_with — Começa / termina com (case-insensitive)
• greater_than / less_than / greater_or_equal / less_or_equal — Pra números
• is_empty / is_not_empty — Vazio (cuidado: 0 e "" também contam como vazio)
• in_array / not_in_array — Um valor dentro de uma lista

Pegadinhas das condições

• equals é case-sensitive. attribution.last.source = Meta_ads é diferente de meta_ads. Use equals apenas pra campos canônicos (slugs, enums); pra texto livre, use contains.
• is_empty em número pega zero também. Se o campo é message_count e a conversa tem 0 mensagens, is_empty passa. Use equals 0 se quiser ser explícito.
• Tag funciona com contains. Pra filtrar contato com tag "VIP", use contact.tags contains VIP. equals compararia o array inteiro (raramente o que você quer).
• attribution.last.* requer touchpoint existente. Contato sem nenhum touchpoint cai em null e qualquer comparação além de is_empty falha em silêncio.

Como criar — passo a passo

Em Automações → Workflows → Novo workflow:

1. Dê um nome descritivo (ex: "Boas-vindas WhatsApp").
2. Adicione um gatilho — Arraste do menu lateral ou clique pra adicionar.
3. Configure o gatilho — Filtros opcionais (ex: só do canal X, só com tag Y).
4. Adicione ações — Encadeie ações conforme o fluxo.
5. Adicione condições se precisar — Bifurcações pra cenários diferentes.
6. Conecte os nodes — Arraste setas saindo de cada node pro próximo.
7. Valide — O editor avisa se faltam conexões, ação sem gatilho, etc.
8. Publique — Workflow só roda depois de publicado. Antes disso, fica como rascunho.

Pegadinhas comuns

• Workflow só roda depois de publicado. Salvar em rascunho não dispara nada. Use o botão "Publicar" depois de testar mentalmente.
• Execuções paralelas não são determinísticas. Se 100 mensagens chegam ao mesmo tempo, 100 workflows rodam em paralelo. Se sua lógica depende de ordem ("primeiro A, depois B"), use ação de delay ou junte em node único.
• Ação "Esperar resposta" pode segurar workflow indefinidamente. Se você espera resposta do cliente e ele some, o workflow fica preso. Combine com delay máximo e fallback.
• Trigger "Webhook" não traz contexto automaticamente. Webhook externo dispara o workflow, mas não traz conversa/contato. Ações que dependem de conversa específica falham. Use só quando o webhook carrega ID do contato/conversa no payload e a primeira ação puxa esse dado.
• Loops sem condição de saída travam. Workflow que dispara outro que dispara o primeiro = loop infinito. Sistema tem proteção, mas evite construir.
• Ações de IA consomem créditos. "Disparar agente de IA" ou "Gerar resposta" não são grátis — cada execução conta no consumo da empresa.
• Workflow não roda retroativamente. Criar workflow hoje pra "quando contato é criado" só pega contatos criados a partir de agora. Pra rodar em contatos antigos, use ações em lote ou disparo manual.

Boas práticas

• Nome descritivo + categoria. Workflows mal nomeados viram lixo em 6 meses. "Boas-vindas WA" é melhor que "WF1".
• Comece simples. 1 gatilho + 2 ações é mais útil que 1 gatilho + 15 ações com 3 condições.
• Teste com você mesmo antes de publicar. Mande mensagem teste pelo canal, veja se workflow roda como esperado.
• Use comentários internos no workflow. Adicione node de "comentário" descrevendo intenção pros futuros editores.
• Audite mensalmente. Workflows ativos que nunca rodam = morto. Workflows que rodam demais = pode estar em loop.

Veja também

• Workflows: exemplos práticos
• Broadcasts e templates HSM