Tema
Gatilhos
O Gatilho é o nó verde que dá início a um fluxo. Toda automação precisa ter exatamente um gatilho como ponto de partida.
Nova Conversa
Dispara quando uma conversa nova é criada com um contato.
Quando usar: para dar as boas-vindas assim que um cliente entra em contato pela primeira vez (ou depois de muito tempo sem conversar). É o gatilho usado pelo preset Boas-vindas.
Configuração: canais permitidos.
Mensagem Recebida
Dispara a cada mensagem recebida do contato.
Quando usar: para reagir a qualquer mensagem, por exemplo para acionar uma Resposta IA que atende automaticamente. É o gatilho usado pelo preset Assistente Inteligente.
Configuração: canais permitidos.
Conversa Reaberta
Dispara quando o contato volta a escrever depois que a conversa já havia sido encerrada.
Quando usar: para dar boas-vindas de volta a um cliente que retoma o contato. É o gatilho usado pelo preset Bem-vindo de Volta.
Configuração: canais permitidos.
Palavra-Chave
Dispara ao detectar palavras específicas na mensagem do contato.
Quando usar: para responder a pedidos específicos, como "orçamento", "cancelar" ou "reclamação", direcionando a conversa para um fluxo próprio. É o gatilho usado pelo preset Pesquisa de Satisfação.
Configuração: lista de palavras-chave (uma por linha) e o modo de comparação:
| Modo | Como compara |
|---|---|
| Contém | Dispara se a mensagem contiver a palavra-chave em qualquer parte do texto. |
| Exato | Dispara só se a mensagem for exatamente igual à palavra-chave. |
| Regex | Dispara com base em uma expressão regular, para regras mais avançadas. |
Resposta Campanha
Dispara quando o contato responde a uma mensagem enviada por uma campanha.
Quando usar: para dar continuidade automática a quem respondeu a um disparo em massa. É o gatilho usado pelo preset Follow-up de Campanha.
Configuração: uma campanha específica ou a opção Qualquer campanha.
Webhook
Dispara quando um sistema externo (CRM, formulário do site, ERP, planilha automatizada) faz um POST na URL do fluxo. É o gatilho para o Columba iniciar a conversa: o contato é localizado ou criado pelo telefone, a conversa nasce no número de WhatsApp escolhido e o fluxo começa na hora, já com os dados recebidos.
Quando usar: um lead entra no CRM e você quer que a IA (ou uma sequência de mensagens) faça o primeiro contato sem ninguém digitar. Também serve para reengajar clientes a partir de eventos de outros sistemas (pedido aprovado, boleto vencido).
Configuração:
| Campo | O que é |
|---|---|
| URL do webhook e Token | Gerados ao salvar o fluxo. O sistema de origem envia o token no header X-Webhook-Token (ou em ?token=). O botão de atualizar gera um token novo e invalida o antigo. |
| Canal | WhatsApp: abre a conversa e o fluxo fala com o contato. Sem canal: o fluxo roda só com ações internas (tags, ficha do contato, funil, tickets, chamada HTTP, avisar equipe), sem abrir conversa; nós de mensagem, IA, aguardar resposta, transferir e encerrar são pulados. |
| Número de WhatsApp | Com canal WhatsApp: por qual número a conversa nasce. Sem escolha, usa o primeiro número público conectado. |
| Telefone (obrigatório), Nome, E-mail | Caminho de cada dado dentro do payload, com ponto para níveis (lead.telefone). Ao receber um evento de teste, os caminhos aparecem na lista e você marca cada um com um clique. |
| DDI padrão | Aplicado quando o telefone vem sem código do país (padrão 55). Telefone com + na frente é respeitado como veio. |
| Tags no contato | Aplicadas ao contato criado ou encontrado. |
| Se este contato já estiver em um fluxo | Só vale para o mesmo contato: contatos diferentes rodam em paralelo, cada um na sua conversa. Reiniciar (padrão) interrompe o fluxo atual daquela conversa e começa este; Ignorar mantém o que estava rodando e só registra o evento. |
Evento de teste: com o painel aberto, o Columba fica ouvindo. Envie um POST (o exemplo em curl está no painel) e o último payload aparece com todos os campos. O fluxo em rascunho só registra o evento; para executar, publique.
Variáveis: tudo que veio no payload fica em {{webhook.campo}}, inclusive níveis aninhados ({{webhook.lead.origem}}). Use em mensagens, no prompt da IA ou em condições. A mensagem "atual" vista pelos nós de IA é um resumo do lead recebido.
Regras de segurança: conversa em atendimento humano nunca é interrompida (o evento fica registrado, o fluxo não roda). Limite de 60 eventos por minuto por fluxo. Contato bloqueado ou descadastrado não recebe nada. A resposta do webhook sempre diz se o fluxo iniciou e, se não, o motivo.
Exemplo de payload
json
{ "lead": { "nome": "Ana Souza", "telefone": "51999990001", "origem": "site" } }Com Telefone = lead.telefone e Nome = lead.nome, o fluxo começa com {{webhook.lead.origem}} valendo site.
Canais permitidos
Todos os gatilhos têm o campo Canais permitidos, com as opções WhatsApp e Webchat. Se nenhum canal for marcado, o gatilho vale para todos os canais.
Números permitidos
Quando a conta tem mais de um número de WhatsApp, o gatilho também aceita Números permitidos: marque um ou mais conectores para o fluxo valer só neles. Sem nenhum marcado, o gatilho vale para todos os números. É o jeito de ter um fluxo exclusivo para o número de um setor — combine com o número exclusivo de um time.
Ordem de prioridade
Se mais de um gatilho se aplicar à mesma situação, apenas o primeiro da ordem abaixo executa:
- Palavra-Chave
- Resposta Campanha
- Nova Conversa
- Conversa Reaberta
- Mensagem Recebida