Description

n8n-nodes-uchat

Custom n8n node para integração com a API uChat (https://www.uchat.com.au/api).

🚀 Open Source – Contribuições são bem-vindas! Veja CONTRIBUTING.md
⚠️ Aviso importante: Este repositório é um fork não-oficial do projeto NicoChat. O uso deste código é por sua conta e risco e não possui suporte oficial do time uChat.

Créditos

Este projeto é baseado no n8n-nodes-nicochat desenvolvido por Nicollas Petrelli, que é disponibilizado sob a licença MIT. Agradecemos pela excelente base de código que permitiu a adaptação para o uChat.

Instalação

Opção 1: Via npm

npm install n8n-nodes-uchat

Opção 2: Instalação local para desenvolvimento

1. Clone o repositório e instale as dependências:

npm install

2. Compile o node:

npm run build

3. Crie um link npm:

npm link

4. No diretório da sua instância n8n:

npm link n8n-nodes-uchat

5. Reinicie o n8n para carregar o novo node.

Configuração

Credenciais

O node usa autenticação via API Key:

1. Acesse https://www.uchat.com.au/settings#/api e obtenha sua chave de API
2. No n8n, crie uma nova credencial "uChat API"
3. Insira sua API Key

Recursos Disponíveis

1. Subscribers (Contatos)

Gerenciamento completo de contatos/assinantes:

• Get – Buscar um contato específico por user_ns ou email
• Create – Criar novo contato com nome, telefone e email
• Update – Atualizar dados de contato existente
• Delete – Remover um contato
• Get Many – Listar contatos com paginação e filtros

2. Tags

Gerenciamento de tags para organização de contatos:

• Add to Subscriber – Adicionar tag a um contato
• Remove from Subscriber – Remover tag de um contato
• Create – Criar nova tag
• Delete – Deletar tag existente
• Get Many – Listar tags com filtros

Nota: A API uChat não suporta edição/atualização de tags. Para "renomear" uma tag, é necessário criar uma nova e deletar a antiga.

3. Custom Fields (Campos Personalizados)

Gerenciamento de campos customizados:

• Get Many – Listar todos os campos personalizados disponíveis
• Set Field Value – Definir valor de campo personalizado para um contato

4. Flow (Fluxos)

Envio e gerenciamento de fluxos:

• Send to Subscriber – Enviar fluxo específico para um contato
• Get Many – Listar fluxos disponíveis

O campo Flow Name possui dropdown dinâmico que lista automaticamente os fluxos disponíveis.

5. Broadcast

Disparos em massa de mensagens:

• Send to Contacts – Enviar broadcast para lista de contatos (user_ns)
• Send to Tags – Enviar broadcast para contatos com tags específicas

6. WhatsApp Templates

Gerenciamento de templates WhatsApp:

• Get Many – Listar templates WhatsApp disponíveis
• Send – Enviar template WhatsApp para um contato

O campo Template possui dropdown dinâmico que lista automaticamente os templates disponíveis.

7. Conversation (Histórico)

Acesso ao histórico de conversas:

• Get History – Obter histórico de conversa de um contato com filtros de data e paginação

8. 🆕 Requisicao Externa uChat Trigger (Webhook)

Trigger node para receber requisições externas do uChat via webhook.

Como Configurar:

1. No n8n:

   • Adicione o node "Requisicao Externa uChat Trigger" ao seu workflow
   • O n8n irá gerar automaticamente uma URL de webhook
   • Copie essa URL (aparece no node após salvar o workflow)

2. No uChat:

   • Abra seu fluxo no uChat
   • Adicione um bloco: Ação > Ação Avançada > Requisição API
   • Configure:
     • URL: Cole a URL do webhook gerada pelo n8n
     • Método: POST
     • Corpo: JSON com os dados que você quer enviar

Parâmetros Disponíveis:

Igual ao webhook padrão do n8n:

• HTTP Method: Método HTTP (POST, GET, PUT, DELETE, PATCH, HEAD)
• Path: Caminho personalizado do webhook
• Authentication: Autenticação (None)
• Respond: Quando responder (Immediately, When Last Node Finishes, Using Respond to Webhook Node)
• Response Code: Código de status HTTP (200, 201, 404, etc.)
• Response Data: Tipo de dados na resposta (quando "When Last Node Finishes")
• Options:
  • Response Headers: Adicionar cabeçalhos customizados na resposta

O que o Trigger Recebe:

O trigger recebe todos os dados enviados pelo uChat e disponibiliza em 3 campos:

• body: Corpo da requisição (JSON enviado pelo uChat)
• headers: Cabeçalhos HTTP
• query: Parâmetros de URL (se houver)

Exemplo de Uso:

Cenário: Quando o uChat enviar dados de um novo contato, salvar no CRM.

1. uChat: Bloco de Ação > Requisição API

   {
       "user_ns": "{{user_ns}}",
       "nome": "{{nome}}",
       "telefone": "{{telefone}}",
       "email": "{{email}}"
   }
   

2. n8n Workflow:

   • Requisição Externa uChat (recebe dados)
   • HTTP Request (salva no CRM)
   • Email (envia notificação)

Estrutura do Projeto

n8n-nodes-uchat/
├── credentials/
│   └── UchatApi.credentials.ts    # Configuração de autenticação
├── nodes/
│   └── Uchat/
│       ├── Uchat.node.ts          # Implementação principal do node
│       ├── Uchat.node.json        # Metadados do node
│       └── uchat.svg              # Ícone do node
├── package.json                       # Configurações e dependências
└── tsconfig.json                      # Configurações TypeScript

Desenvolvimento

Scripts disponíveis

• npm run build – Compila o TypeScript
• npm run build:watch – Compila com watch mode (detecta mudanças)
• npm run lint – Verifica código com ESLint
• npm run format – Formata código com Prettier
• npm run dev – Inicia n8n com o node carregado

Build

O projeto está configurado com build automático via workflow. Qualquer alteração nos arquivos TypeScript será automaticamente compilada.

Exemplos de Uso

Criar novo contato e adicionar tag

1. Node uChat – Resource: Subscriber, Operation: Create

   • Name: "João Silva"
   • Phone: "5511999999999"
   • Email: "joao@example.com"

2. Node uChat – Resource: Tag, Operation: Add to Subscriber

   • User NS: {{ $json.user_ns }} (do node anterior)
   • Tag Name: "Cliente VIP"

Enviar fluxo para contatos com tag específica

1. Node uChat – Resource: Broadcast, Operation: Send to Tags
   • Tags: "Cliente VIP"
   • Message: "Sua mensagem aqui"

Atualizar campo personalizado

1. Node uChat – Resource: Custom Field, Operation: Set Field Value
   • User NS: "user_ns_do_contato"
   • Field Name: "ultima_compra"
   • Field Value: "2025-10-24"

Obter histórico de conversa

1. Node uChat – Resource: Conversation, Operation: Get History
   • User NS: "user_ns_do_contato"
   • Options:
     • Date From: "2025-10-01"
     • Date To: "2025-10-24"
     • Limit: 50

Limitações

• Tag Edit: A API uChat não suporta atualização/edição de tags. Para renomear, é necessário criar nova tag e deletar a antiga.

Mapeamento de Endpoints

Suporte

Para dúvidas sobre a API uChat, consulte a documentação oficial em https://www.uchat.com.au/api

Licença

MIT