chatwoot-ura

n8n community node para URA no Chatwoot montada no canvas: um node por menu, botões, palavras-chave, perguntas e transferência

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.1
Author: Danilo

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:

  1. no menu inicial;
  2. 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:

  1. pelo número da opção: 2, 2 - suporte, 2);
  2. pelo título ou por uma palavra-chave igual ao texto inteiro: é o que
    chega quando o cliente toca no botão;
  3. 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
E-Mail 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

  1. 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ô.
  2. 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 use
SAFE_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).

Licença

MIT

Discussion