chatfunnel

n8n community node para a API pública do ChatFunnel v1 (contatos, tags, kanbans, templates WhatsApp, fluxos, canais e campos personalizados)

Package Information

Downloads: 2 weekly / 48 monthly
Latest Version: 2.0.0
Author: ChatFunnel

Available Nodes

ChatFunnel icon
ChatFunnel
Interagir com a API pública do ChatFunnel v1

Documentation

n8n-nodes-chatfunnel

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

Cobre 100% dos 18 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 Criar Card POST /kanbans/{kanbanId}/cards
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.
  • Mover card por contato: nas operações de 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

Discussion