Node comunitário do n8n para usar a API do CodeChat WhatsApp em workflows.
Com este pacote você pode conectar instâncias do WhatsApp, enviar mensagens, gerenciar chats, fazer upload e download de mídias, trabalhar com grupos, configurar webhooks, controlar chamadas simples e iniciar workflows por eventos WebSocket da CodeChat diretamente no n8n.
- Instalação
- Credenciais
- Recursos e operações
- Como usar
- Desenvolvimento
- Publicação
- Compatibilidade
- Links úteis
No n8n:
- Abra Settings.
- Acesse Community Nodes.
- Clique em Install.
- Informe
n8n-nodes-codechat. - Confirme a instalação.
Veja também o guia oficial de instalação de community nodes do n8n.
npm install n8n-nodes-codechatCrie uma credencial do tipo CodeChat API no n8n com os campos abaixo:
- Base URL: URL da sua API CodeChat, por exemplo
https://api.example.com. - Instance Name: instância padrão que será usada pelo node.
- Instance Token: token de autenticação da instância.
As operações e os triggers por instância usam a instância configurada nessa credencial.
Para eventos globais, crie uma credencial do tipo CodeChat User API:
- Base URL: URL da sua API CodeChat.
- User Token: JWT de usuário usado pelo endpoint global de eventos.
Use CodeChat API para eventos e ações de uma instância. Use CodeChat User API somente para o CodeChat Global Trigger.
- Buscar uma instância
- Verificar status da conexão
- Conectar com QR code
- Conectar com código no telefone
- Fazer logout
- Enviar texto
- Enviar mídia por URL ou ID de upload
- Enviar mídia a partir de arquivo binário do n8n
- Enviar link com preview
- Enviar localização
- Enviar contato
- Enviar reação
- Enviar resposta
- Enviar botões, botão de copiar código, botão de URL, PIX, solicitação de pagamento, PPT e carrossel
- Arquivar ou desarquivar chat
- Checar contas de WhatsApp por número
- Apagar mensagem
- Editar mensagem
- Buscar foto de perfil
- Marcar mensagens como lidas
- Rejeitar chamada pela API de chat
- Abrir uma chamada
- Rejeitar chamada
- Desligar chamada
- Listar chamadas com filtros
- Recuperar uma chamada
- Tocar áudio na chamada por URL ou arquivo binário
- Parar áudio da chamada
- Iniciar gravação
- Parar gravação
- Fazer download de gravações e faixas de áudio/vídeo da chamada
- Fazer upload de mídia por arquivo binário do n8n
- Listar mídias com filtros
- Buscar metadados de uma mídia
- Fazer download do conteúdo de uma mídia
- Fazer download de mídia de mensagem por conteúdo, ID de banco ou ID da chave da mensagem
- Excluir mídia enviada
- Criar grupo
- Buscar código de convite
- Revogar código de convite
- Sair do grupo
- Adicionar, remover, promover ou rebaixar participantes
- Atualizar imagem do grupo
- Buscar configuração de webhook
- Definir URL do webhook
- Ativar ou desativar webhook
- Configurar eventos inscritos
Os triggers usam exclusivamente WebSocket e não criam webhooks. A URL WebSocket é derivada automaticamente da Base URL da credencial:
https://api.example.comvirawss://api.example.comhttp://localhost:8084viraws://localhost:8084
A CodeChat assina exatamente um evento por conexão WebSocket. Por isso, cada trigger tem um único campo Event do tipo seleção simples.
Inicia o workflow quando um evento normal da instância ocorre em /ws/instance/events.
Credencial usada: CodeChat API com JWT de instância.
Eventos disponíveis:
- Chat Deleted
- Chat Updated
- Connection Updated
- Contact Created or Updated
- Contact Updated
- Group Created or Updated
- Group Participants Updated
- Group Updated
- History Synced
- Identity Updated
- Instance Status Updated
- Label Association Changed
- Label Edited
- Media Retry
- Message Deleted
- Message Received
- Message Starred
- Message Undecryptable
- Message Updated
- Newsletter Event
- Presence Updated
- Profile Picture Updated
- QR Code Updated
- Send Message Result
- Settings Updated
- User About Updated
Inicia o workflow quando um evento JSON de chamada ocorre em /ws/instance/events.
Credencial usada: CodeChat API com JWT de instância.
Esse trigger não usa o WebSocket binário de mídia de chamadas.
Eventos disponíveis:
- Answered Elsewhere
- Call Active
- Call Connecting
- Call Ended
- Call Ended Unconfirmed
- Call Ending
- Call Ready
- Call Ringing
- Call Upsert
- Hangup Requested
- Incoming Call
- Outgoing Call
- Recording Completed
- Recording Deleted
- Recording Expired
- Recording Failed
- Recording Partial
- Recording Started
- Recording Unavailable
- Rejected Elsewhere
- Terminate Confirmed
- Terminate Failed
- Terminate Retry
- Terminate Sent
- Video Playback Completed
- Video Playback Failed
- Video Playback Started
- Video Playback Stopped
Inicia o workflow quando um evento global ocorre em /ws/global/events.
Credencial usada: CodeChat User API com JWT de usuário.
Eventos disponíveis:
- Batch Completed
- Batch Completed With Errors
- Batch Created
- Batch Interrupted
- Batch Item Failed
- Batch Item Unknown
- Batch Paused
- Batch Pause Requested
- Batch Progress
- Batch Recovered
- Batch Resumed
- Batch Scheduled
- Batch Started
- Batch Stop Requested
- Batch Stopped
- Batch Waiting Instance
- Batch Waiting Window
- Batch Window Started
Cada mensagem recebida dispara uma execução do workflow com o payload original da CodeChat preservado. Assim você pode usar expressões como:
{{$json.event}}
{{$json.instance}}
{{$json.instanceId}}
{{$json.data}}
{{$json.timestamp}}
Para eventos de chamadas:
{{$json.call.id}}
{{$json.call.status}}
{{$json.call.peer}}
Quando a conexão cai de forma transitória, o trigger tenta reconectar com exponential backoff e jitter, limitado a aproximadamente 30 segundos. Fechamentos permanentes como token expirado ou escopo inválido encerram o trigger com erro em vez de criar loop infinito.
- Adicione o node CodeChat em um workflow do n8n.
- Selecione a credencial CodeChat API.
- Escolha o recurso desejado: Instance, Message, Chat, Call, Media, Group ou Webhook.
- Escolha a operação.
- Preencha os campos obrigatórios e execute o node.
Para operações com arquivos, como upload de mídia ou envio de áudio em chamada, passe dados binários de um node anterior do n8n e informe o nome correto do campo binário.
Para testar um trigger no editor do n8n, adicione CodeChat Trigger, CodeChat Calls Trigger ou CodeChat Global Trigger, selecione a credencial correta, escolha um evento e clique em Listen for test event. O n8n abre uma conexão temporária e executa o workflow quando o próximo evento selecionado chegar.
Instale as dependências:
npm installGere o build:
npm run buildRode o lint:
npm run lintInicie o n8n em modo de desenvolvimento:
npm run devConfira o conteúdo que será empacotado para o npm:
npm pack --dry-runEste projeto usa o fluxo oficial do n8n-node para release. Publique com:
npm run releaseO comando direto npm publish é bloqueado pelo prepublishOnly e orienta o uso de npm run release.
Antes de publicar, confirme que a conta npm está autenticada:
npm login
npm whoami- API version de community nodes do n8n:
1 - Strict mode: habilitado
- Node.js recomendado: versão LTS atual ou versão mais nova suportada pelo n8n