Package Information
Documentation
n8n-nodes-chatwoot-ura
Community node do n8n para montar uma URA no Chatwoot
direto no canvas: cada menu e cada pergunta é um node, ligado ao próximo pelas
saídas das opções, como qualquer fluxo do n8n. Botões no WhatsApp e no widget
do site, palavras-chave, validação de CPF/CNPJ, transferência para humano e
encerramento.
[Chatwoot URA Trigger] ─► [Menu Principal ★]
│ ├ Financeiro ──────► [Menu Financeiro] ─ 2ª via ─► [Pergunta CPF]
│ ├ Suporte técnico ─► [Transferir] │
│ └ Sem resposta ────► [Transferir] Resposta
│ ▼
└────────────────────────────────────────────► [Menu Mais Alguma Coisa] ◄─ [Hubsoft] ─► [Mensagem]
A etapa em que cada cliente está fica gravada na própria conversa do Chatwoot
(custom attributes): não há banco extra, e o atendente vê no painel onde o
cliente parou.
Os nodes
Chatwoot URA Trigger. Recebe o webhook do robô do Chatwoot, confere a
assinatura e só dispara para resposta do cliente em conversa que ainda está com
o robô. Os ajustes gerais da URA ficam nele: palavras para voltar ao início e
o tempo de inatividade que reinicia a URA.
Chatwoot URA, com cinco operações:
| Operação | O que faz | Saídas |
|---|---|---|
| Menu | Envia o texto e as opções como botões, e espera a escolha | uma por opção + Sem Resposta Válida |
| Pergunta | Envia a pergunta, valida a resposta e guarda em dados |
Resposta + Sem Resposta Válida |
| Enviar Mensagem | Envia um texto e segue | uma |
| Transferir Para Atendente | Atribui equipe/agente e passa a conversa para humano | uma |
| Encerrar Conversa | Envia a despedida e resolve a conversa | uma |
Onde ligar o trigger
Ligue a saída do trigger:
- no menu inicial;
- em todo Menu ou Pergunta que venha logo depois de um node que não é da
URA (Hubsoft, IF, Code…).
O resto se resolve sozinho. Cada mensagem do cliente sai do trigger e é
repassada de node da URA em node da URA, pelas saídas das opções, até o
menu ou a pergunta em que a conversa está. O repasse nunca passa por um node
de outro tipo: um Hubsoft que recebesse o item seria executado à toa. É por
isso que o menu depois dele precisa da ligação própria.
Se faltar uma ligação, o node falha na primeira vez em que é usado, com a
mensagem "A resposta do cliente não chega ao node…".
Os nodes repassados aparecem na execução do n8n como executados, mas não
enviam nada: só passam o item adiante.
Para saber quais saídas levam a nodes da URA, o node lê as ligações do
workflow no contexto interno de execução do n8n, que não tem API pública para
isso. Se uma versão futura do n8n esconder essa informação, o repasse para, e
todo Menu e Pergunta volta a precisar da ligação direta do trigger. A mensagem
de erro avisa.
As saídas das opções ligam um node ao próximo: é o caminho que a conversa
percorre. Pode ligar para trás (um "Voltar" apontando para o Menu Principal).
Menu
- Menu Inicial: marque em um menu. Ele recebe as conversas novas e é
para onde o cliente volta com "menu" ou depois de inativo. - Mensagem: aceita
{contato.primeiro_nome},{contato.nome},{contato.telefone},{dados.campo}e expressões do n8n. - Opções: cada uma tem Título (o texto do botão), Palavras-Chave e
Descrição opcional. Cada opção vira uma saída, na mesma ordem.
Como a resposta do cliente é reconhecida, nesta ordem:
- pelo número da opção:
2,2 - suporte,2); - pelo título ou por uma palavra-chave igual ao texto inteiro: é o que
chega quando o cliente toca no botão; - por título ou palavra-chave dentro de uma frase: com
suporte, ajuda, help, a mensagem "preciso de ajuda com a internet" cai em Suporte.
Maiúsculas, acentos e pontuação não importam. A palavra-chave precisa aparecer
inteira: ajuda não casa com "ajudante".
Resposta que não casa com nenhuma opção reenvia o menu com um aviso, numa
mensagem só. Depois de Máximo de Tentativas inválidas seguidas (padrão 3), a
conversa sai por Sem Resposta Válida. Ligue essa saída a um Transferir, por
exemplo.
Pergunta
| Validação | Aceita | Guarda |
|---|---|---|
| Qualquer Texto | qualquer coisa não vazia | o texto |
| Número | só dígitos | os dígitos |
| CPF | CPF com dígitos verificadores corretos, com ou sem pontuação | só os números |
| CPF Ou CNPJ | qualquer um dos dois | só os números |
| formato de e-mail | em minúsculas | |
| Expressão Regular | o que casar com a regex | o texto |
A resposta válida vai para dados.<Salvar Como> e sai em Resposta, com o
item { resposta, dados, contato, conversa }. No próximo node, use{{ $json.dados.cpf }}.
Depois de um node de terceiro
Um node como o Hubsoft troca o conteúdo do item. Os nodes da URA que vêm
depois acham a conversa sozinhos, pelo vínculo entre itens (paired item) até
o trigger, e leem os dados atualizados no Chatwoot. Nas mensagens, continue
usando {dados.cpf}. Para os dados do Hubsoft, use expressões normais do n8n
({{ $json.link }}).
Antes de agir, todo node que recebe o fluxo confere no Chatwoot se a conversa
ainda está com o robô. Se um atendente assumiu no meio do caminho, ele não envia
nada e o fluxo para ali.
Configuração no Chatwoot
- Configurações → Robôs → Adicionar robô. Em URL do Webhook, cole a URL
de produção do Chatwoot URA Trigger. Guarde o Access Token e o
Secret do robô. - Configurações → Caixas de Entrada → (a caixa) → aba do robô: escolha o
robô. A partir daí, toda conversa nova nasce Pendente (com o robô).
Quando fica Aberta, está com um humano.
Conversas que já estavam abertas antes do vínculo continuam com humanos. Para
testar numa delas, resolva a conversa e mande uma mensagem nova.
O Chatwoot espera a resposta do webhook por 5 segundos e, se o robô falhar,
passa a conversa para atendimento humano. Se o n8n estiver em rede interna, as
versões novas do Chatwoot bloqueiam o webhook; nesse caso useSAFE_FETCH_ALLOW_PRIVATE_NETWORK=true no Chatwoot, ou o endereço público do
n8n.
Credencial
| Campo | Exemplo | Observação |
|---|---|---|
| URL do Chatwoot | https://chat.exemplo.com.br |
sem /api |
| Token do Agent Bot | •••• |
o token do robô, não o de um usuário |
| Secret do Webhook | •••• |
o secret do robô. Vazio desliga a conferência da assinatura |
O botão de teste reconhece se o token é de robô válido, de usuário ou
inválido.
Começando pelo exemplo
exemplos/ura-provedor.json traz uma URA de
provedor pronta: Menu Principal, Financeiro, Pergunta de CPF/CNPJ, um node no
lugar da consulta ao Hubsoft, "Posso ajudar em mais alguma coisa?",
Transferir e Encerrar. O trigger liga só no Menu Principal e no "Posso ajudar
em mais alguma coisa?", que vem depois do node do Hubsoft. Abra o arquivo, copie tudo e cole no canvas do n8n com
Ctrl+V. Depois, selecione a credencial em cada node.
Botões por canal
| Canal | Resultado |
|---|---|
| WhatsApp (Cloud/360dialog) | até 3 opções → botões; 4 a 10 → lista |
| Widget do site | botões |
| Caixa API (Evolution, WAHA…) e outros | depende da integração |
Numerar Opções no Texto (padrão Automático) repete as opções como lista
numerada fora do WhatsApp e do widget.
Só o WhatsApp tem limite: no máximo 10 opções, título com até 20
caracteres em botão (até 3 opções, sem descrição) e até 24 em lista. Um
menu fora disso, numa conversa de WhatsApp, vai como lista numerada no
texto, com um aviso na execução do n8n. A Meta recusaria os botões sem
avisar, e o cliente ficaria sem resposta. Nos outros canais, o menu vai
sempre com botões.
Estado na conversa
| Custom attribute | Conteúdo |
|---|---|
ura_etapa |
nome do node (menu ou pergunta) que espera a resposta |
ura_dados |
dados coletados, em JSON ({"cpf":"…"}) |
ura_tentativas |
respostas inválidas seguidas |
ura_mensagem |
ID da mensagem do menu pendente (clique no widget) |
ura_atualizado |
última interação (unix) |
Escolher uma opção ou responder uma pergunta tira a conversa da espera. Se o
caminho terminar sem outro Menu ou Pergunta, a próxima mensagem do cliente
recomeça pelo menu inicial. O mesmo vale se o node da etapa for renomeado ou
desligado do trigger. Na transferência e no encerramento, ura_dados fica
gravado, para o atendente ver o que o cliente informou.
Limitação conhecida
Duas mensagens do mesmo cliente em menos de um segundo podem ser processadas ao
mesmo tempo e ler a mesma etapa. Em URA de botões isso é raro.
Da 0.1.x para a 0.2
A 0.2 troca o fluxo em JSON (operações Processar Mensagem e Ir Para Etapa)
por um node por menu. Workflows da 0.1 precisam ser remontados; o exemplo acima
é o ponto de partida. Conversas em andamento recomeçam pelo menu inicial.
Instalação
Pelo n8n: Settings → Community nodes → Install → n8n-nodes-chatwoot-ura.
Desenvolvimento
npm install --ignore-scripts # o isolated-vm só compila com Visual Studio, e o build não precisa dele
npm run build
npm run test:smoke
npm run lint
O smoke test simula uma URA inteira: um mini-executor no lugar do n8n e um
Chatwoot falso, do "oi" à transferência e ao encerramento. Também confere o
workflow de exemplo. Com CHATWOOT_URL e CHATWOOT_TOKEN no .env, confere o
token; com CHATWOOT_CONTA e CHATWOOT_CONVERSA, lê uma conversa (só GET).
Publicação no npm: set RELEASE_MODE=true e npx -y npm@11 publish --access public
(o npm exige 2FA).