n8n-nodes-uniteds-whatsapp

Este é um pacote de Community Node para n8n que permite integração com a API WhatsApp da Uniteds.

n8n é uma plataforma de automação de workflows extensível e de código aberto.

🚀 Instalação

Community Nodes (Recomendado)

1. Acesse Settings > Community Nodes
2. Clique em Install
3. Digite: n8n-nodes-uniteds-whatsapp
4. Clique em Install

Manual (Via npm)

npm install n8n-nodes-uniteds-whatsapp

🔑 Credenciais

Para usar este node, você precisa:

1. Criar uma conta em https://wpp.uniteds.com.br
2. Acessar o menu "Tokens de API"
3. Criar um novo token:
   • Clique em "Novo Token"
   • Nome: Ex: "N8N Production"
   • Selecione permissões necessárias (ou marque "all")
   • Copie o token gerado (formato: wpp_48caracteres)
4. Adicionar as credenciais no n8n:
   • API URL: https://apiwp.uniteds.com.br/api (padrão)
   • API Token: Cole o token gerado

📦 Nodes Inclusos

1. Uniteds WhatsApp (Node Regular)

Node para executar ações na API WhatsApp.

Resources:

• Message: Enviar mensagens

  • Send Text
  • Send Image
  • Send Document
  • Send Audio
  • Send Video

• Instance: Gerenciar instâncias

  • Create
  • Get Status
  • Get QR Code
  • Disconnect
  • Delete

2. Uniteds WhatsApp Trigger (Webhook)

Node de gatilho que escuta eventos do WhatsApp via webhook.

✨ Novidade v1.3.0: Seleção Automática de Instâncias

Agora o trigger possui um dropdown inteligente que:

• 📋 Lista automaticamente todas as suas instâncias
• ✅ Mostra o status atual de cada instância
• 🔄 Auto-configura o webhook ao ativar o workflow
• 🎯 Usa os novos endpoints /api/n8n/* com API Token

Formato do dropdown:

Nome da Instância (status)
Exemplo: Meu WhatsApp (connected) ✅

Eventos Suportados:

• Message Received: Quando uma mensagem é recebida
• Message Sent: Quando uma mensagem é enviada
• Message Ack: Quando uma mensagem é confirmada
• QR Code Updated: Quando o QR Code é atualizado
• Connection State: Quando o estado da conexão muda
• All Events: Todos os eventos (✨ auto-configura webhook)

Filtros:

• Only From Me: Receber apenas mensagens enviadas por você
• Ignore Group Messages: Ignorar mensagens de grupos
• Filter Number: Filtrar mensagens de um número específico

📚 Exemplos de Uso

Exemplo 1: Enviar Mensagem de Texto

Trigger → Uniteds WhatsApp (Send Text)

Configuração:

• Resource: Message
• Operation: Send Text
• Instance ID: my-instance
• Phone Number: 5511999999999
• Message: Olá! Como posso ajudar?

Exemplo 2: Receber Mensagens e Responder Automaticamente (✨ v1.3.0)

Uniteds WhatsApp Trigger → Function → Uniteds WhatsApp (Send Text)

Trigger Config:

• Instance: Selecione do dropdown (ex: "Meu WhatsApp (connected)")
• Events: Message Received
• Ignore Group Messages: Yes

Novo comportamento:

• ✅ Webhook configurado automaticamente ao ativar
• ✅ Não precisa mais copiar/colar Instance ID
• ✅ Valida se a instância está conectada

Function:

return {
  to: $json.data.from,
  message: `Obrigado pela mensagem: "${$json.data.body}"`
};

Exemplo 3: Enviar Imagem com Legenda

Trigger → Uniteds WhatsApp (Send Image)

Configuração:

• Resource: Message
• Operation: Send Image
• Instance ID: my-instance
• Phone Number: 5511999999999
• Media URL: https://example.com/image.jpg
• Caption: Confira esta imagem!

Exemplo 4: Criar Nova Instância e Obter QR Code

Trigger → Uniteds WhatsApp (Create) → Uniteds WhatsApp (Get QR Code)

Step 1 - Create:

• Resource: Instance
• Operation: Create
• Instance Name: Nova Instância

Step 2 - Get QR Code:

• Resource: Instance
• Operation: Get QR Code
• Instance ID: {{ $json.instanceId }}

🔧 Desenvolvimento

Requisitos

• Node.js >= 16
• npm >= 7

Setup

# Clone o repositório
git clone https://github.com/uniteds/n8n-nodes-uniteds-whatsapp.git

# Instale as dependências
cd n8n-nodes-uniteds-whatsapp
npm install

# Build
npm run build

# Link localmente para teste
npm link

Build

npm run build

Lint

npm run lint
npm run lintfix

📄 Licença

MIT

🤝 Suporte

• Documentação API: https://apiwp.uniteds.com.br/docs
• Email: contato@uniteds.com.br
• Website: https://uniteds.com.br

🐛 Reportar Bugs

Encontrou um bug? Abra uma issue em: GitHub Issues

⭐ Recursos

• Suporte completo à API WhatsApp Uniteds
• Webhook/Trigger para eventos em tempo real
• Envio de mensagens (texto, imagem, vídeo, áudio, documentos)
• Gerenciamento de instâncias
• Filtros avançados para webhooks
• TypeScript
• Testes de credenciais automáticos

📝 Changelog

v1.3.0 (2024-11-07)

🎉 Grandes Melhorias no Trigger:

• ✨ Dropdown de instâncias: Selecione visualmente suas instâncias (antes: campo texto manual)
• ✨ Auto-configuração de webhook: Webhook configurado automaticamente ao ativar workflow
• ✨ Integração com API Tokens: Usa novo sistema de tokens permanentes (antes: JWT temporário)
• ✨ Novos endpoints N8N: /api/n8n/* otimizados para automação
• ✨ Validação em tempo real: Mostra status de cada instância no dropdown
• 🔒 Permissões granulares: Controle preciso por token
• 📊 Rastreamento de uso: Acompanhe uso dos tokens no painel

Migração v1.2.0 → v1.3.0:

1. Gere um API Token no painel (menu "Tokens de API")
2. Atualize credenciais no N8N com o novo token
3. Reabra seus workflows e use o dropdown de instâncias
4. Documentação completa: API_TOKENS_INTEGRATION.md

v1.2.0

• Melhorias de estabilidade
• Correções de bugs

v1.1.0

• Novos recursos de mensagens
• Filtros avançados

v1.0.0 (2025-01-01)

• Lançamento inicial
• Suporte para envio de mensagens
• Suporte para gerenciamento de instâncias
• Trigger node com webhooks
• Filtros avançados