n8n-nodes-chatfunnel

Community node do n8n para a API pública do ChatFunnel v1 (https://api.chatfunnel.com.br/v1).

Cobre 100% dos 20 endpoints da API: contatos, tags, campos personalizados, canais, fluxos de automação, kanbans (cards) e templates de WhatsApp.

Documentação oficial da API: https://chatfunnel.readme.io/reference

Recursos e operações

| Recurso | Operação | Endpoint | |---|---|---| | Contato | Criar ou Atualizar (upsert) | POST /contacts | | Contato | Atualizar | PUT /contacts/{contactId} | | Contato | Buscar | GET /contacts/search | | Contato | Excluir | DELETE /contacts/{contactId} | | Canal | Listar | GET /channels | | Campo Personalizado | Listar | GET /customFields | | Campo Personalizado | Criar | POST /customFields | | Fluxo (Automação) | Listar | GET /flows | | Fluxo (Automação) | Executar | POST /flows/execute | | Kanban | Listar | GET /kanbans | | Kanban | Mover ou Criar Card (por contato) | POST /kanbans/{kanbanId}/cards | | Kanban | Criar Card (sempre novo) | POST /kanbans/{kanbanId}/card/create | | Kanban | Mover Card (por ID) | POST /kanbans/{kanbanId}/cards/{cardId}/move | | Kanban | Atualizar Card | PUT /kanbans/{kanbanId}/cards/{cardIdOrContactId} | | Kanban | Excluir Card | DELETE /kanbans/{kanbanId}/cards/{cardId} | | Tag | Listar | GET /tags | | Tag | Criar | POST /tags | | Tag | Excluir | DELETE /tags/{tagId} | | Template WhatsApp | Listar | GET /templates | | Template WhatsApp | Enviar | POST /templates/send |

Destaques

• Dropdowns dinâmicos: tags, campos personalizados, canais, fluxos, kanbans, colunas do kanban, motivos de perda e templates são carregados direto da API. Nada de colar UUID na mão.
• Credencial com teste embutido: ao salvar a API key, o n8n valida a chave contra GET /v1/tags.
• Usável como ferramenta de AI Agent (usableAsTool, requer n8n >= 1.79).
• Upsert nativo: Contato > Criar ou Atualizar usa o comportamento de upsert do POST /contacts.
• Atribuição de origem (UTM): a criação de contato aceita utmSource, utmMedium, utmCampaign, utmTerm, utmContent e os campos de agendamento lastScheduleLink/lastScheduleDate. Esses campos existem só no POST /contacts (o update via PUT não os aceita).
• Três operações de card distintas: Mover ou Criar Card (por contato) faz upsert (move o card ativo do contato ou cria); Criar Card (sempre novo) força um card novo; Mover Card (por ID) move um card pelo seu UUID.
• Mover card por contato: nas operações de atualizar/excluir card, o segundo identificador aceita o ID do card ou o ID do contato vinculado.

Credencial

1. No ChatFunnel, gere uma API key com as permissões necessárias:
   • SEARCH_CONTACT — buscar contato
   • CREATE_CONTACT — criar/atualizar/excluir contato
   • MANAGE_ACCOUNT — canais, campos personalizados, fluxos, tags e templates
   • MANAGE_KANBAN — kanbans e cards
2. No n8n: Credentials > New > ChatFunnel API e cole a chave.

A API autentica via query string (?apikey=...). Use apenas em workflows de backend; a chave aparece em logs de proxy.

Instalação

Opção 1: Community node pelo painel do n8n (recomendado)

Requer n8n self-hosted com community nodes habilitados (N8N_COMMUNITY_PACKAGES_ENABLED=true, padrão em self-host).

1. No n8n: Settings > Community Nodes > Install
2. Informe o nome do pacote: n8n-nodes-chatfunnel
3. Confirme o aviso de risco e instale
4. O node "ChatFunnel" aparece na busca de nodes do editor

Se o pacote ainda não estiver publicado no npm, use a Opção 2 (instalação via GitHub) ou publique com npm publish.

Opção 2: Instalação manual via GitHub (Docker)

# dentro do container ou no volume do n8n
cd ~/.n8n
mkdir -p nodes && cd nodes
npm install git+https://github.com/ddiasmatt/n8n-nodes-chatfunnel.git

Depois reinicie o n8n:

docker restart n8n
# ou, em Docker Swarm:
docker service update --force <stack>_n8n

Opção 3: Build local para desenvolvimento

git clone https://github.com/ddiasmatt/n8n-nodes-chatfunnel.git
cd n8n-nodes-chatfunnel
npm install
npm run build

# linka o pacote no diretório de custom nodes do n8n
cd ~/.n8n/nodes   # crie se não existir: mkdir -p ~/.n8n/nodes
npm install /caminho/para/n8n-nodes-chatfunnel

Reinicie o n8n após instalar. O node aparece como ChatFunnel e a credencial como ChatFunnel API.

Desenvolvimento

npm install        # instala dependências
npm run build      # compila TypeScript + copia ícone para dist/
npm run dev        # build em watch mode
npm test           # roda a suíte Jest

Estrutura:

credentials/ChatFunnelApi.credentials.ts   # credencial (auth via query string + teste)
nodes/ChatFunnel/
├── ChatFunnel.node.ts                     # definição do node + roteador de execução
├── GenericFunctions.ts                    # request autenticado e helpers
├── LoadOptions.ts                         # dropdowns dinâmicos (tags, kanbans, colunas...)
├── actions/                               # um handler por recurso
│   ├── ContactActions.ts
│   ├── AccountActions.ts                  # canais, campos personalizados, fluxos, tags
│   ├── KanbanActions.ts
│   └── TemplateActions.ts
└── descriptions/                          # propriedades de UI por recurso

Breaking change (v2.0.0)

A v2 abandona os endpoints legados de webhook (/webhook/create_contact etc.) e usa exclusivamente a API pública v1 (https://api.chatfunnel.com.br/v1). Workflows criados com a v1.x do pacote precisam ser reconfigurados:

• Tags e campos personalizados agora são referenciados por UUID (selecionáveis via dropdown)
• Listar Moderadores foi removido (não existe na API pública v1)
• Card de kanban não tem mais title/description; o card é do contato e aceita comment, priority, amount, statusOportunity
• Envio de template agora exige channelId (selecione o canal WhatsApp no dropdown)

Licença

MIT