n8n Community Nodes - Chatwoot Complete Integration

Integração completa e atualizada das APIs do Chatwoot para n8n

Este é o pacote mais completo de community nodes para integrar o Chatwoot com n8n, cobrindo todas as três categorias de APIs: Application, Client e Platform.

📋 Índice

• Sobre
• Recursos
• Instalação
• Autenticação
• Recursos Disponíveis
• Exemplos de Uso
• Troubleshooting
• Desenvolvimento
• Contribuindo
• Licença

🎯 Sobre

Este projeto foi desenvolvido por Yuri Silva para fornecer uma integração completa, robusta e atualizada entre o Chatwoot e o n8n, seguindo rigorosamente a documentação oficial do Chatwoot.

Diferencial

Enquanto outros nodes do Chatwoot cobrem funcionalidades básicas, este pacote oferece:

✅ Cobertura Completa: Todos os 24+ recursos das APIs oficiais
✅ 3 Tipos de API: Application, Client e Platform APIs
✅ Sempre Atualizado: Segue a documentação oficial na ordem correta
✅ Testado: Validado em instâncias reais Cloud e Self-hosted
✅ Código Limpo: TypeScript, modular e bem documentado
✅ UX Superior: Resource Locators, validações e mensagens claras

🚀 Recursos

Application APIs (20 recursos)

Automação e operações para agentes/administradores:

| Recurso | Operações | Descrição | |---------|-----------|-----------| | Account | Get | Detalhes da conta | | Audit Logs | Get All | Logs de auditoria | | AgentBots | Create, Get, Get All, Update, Delete | Gestão de bots | | Agents | Get All, Create, Update, Delete | Gestão de agentes | | Canned Responses | Get All, Create, Update, Delete | Respostas prontas | | Custom Attributes | Get All, Create, Update, Delete | Atributos personalizados | | Contacts | Get, Get All, Create, Update, Delete, Search | Gestão completa de contatos | | Contact Labels | Get All, Add, Remove | Etiquetas de contatos | | Automation Rules | Get All, Create, Update, Delete | Regras de automação | | Help Center | Get All, Create, Update, Delete | Central de ajuda/portais | | Conversations | Get, Get All, Create, Update, Toggle Status | Gestão de conversas | | Conversation Assignments | Assign, Unassign | Atribuir conversas | | Inboxes | Get, Get All, Create, Update, Delete | Gestão de caixas de entrada | | Messages | Get All, Create, Delete, Update | Gestão de mensagens | | Integrations | Get All, Create, Update, Delete | Gestão de integrações | | Profile | Get, Update | Perfil do usuário | | Teams | Get All, Create, Update, Delete | Gestão de equipes | | Custom Filters | Get All, Create, Update, Delete | Filtros personalizados | | Webhooks | Get All, Create, Update, Delete | Gestão de webhooks | | Reports | Get Account, Get Agent, Conversations | Relatórios diversos |

Client APIs (3 recursos)

Para construir interfaces de chat customizadas:

| Recurso | Operações | Descrição | |---------|-----------|-----------| | Contacts | Create, Get, Update | Criar e gerenciar contatos via client | | Conversations | Get All, Create, Get Messages | Conversas do cliente | | Messages | Create, Update | Enviar e atualizar mensagens |

Platform APIs (4 recursos)

Gerenciamento administrativo (apenas self-hosted):

| Recurso | Operações | Descrição | |---------|-----------|-----------| | Accounts | Get, Get All, Create, Update, Delete | Gestão de contas | | Account Users | Get All, Create, Delete | Usuários de conta | | AgentBots | Get, Get All, Create, Update, Delete | Bots da plataforma | | Users | Get, Get All, Create, Update, Delete | Gestão de usuários |

📦 Instalação

Via n8n Interface (Recomendado)

1. No n8n, vá em Settings → Community Nodes
2. Clique em Install
3. Digite: n8n-nodes-chatwoot-complete
4. Clique em Install
5. Reinicie o n8n

Via npm (Manual)

npm install n8n-nodes-chatwoot-complete

Em seguida, reinicie o n8n para carregar os nodes.

Requisitos

• n8n: >= 0.200.0
• Node.js: >= 18.x
• Chatwoot: Cloud ou Self-hosted (versões recentes)

🔐 Autenticação

Este pacote oferece 3 tipos de credenciais para diferentes casos de uso:

1. Application API (Mais Comum)

Use para automações de agente/admin.

Como obter:

1. Faça login no Chatwoot
2. Vá em Profile Settings (canto superior direito)
3. Clique em Access Token
4. Copie o token

Configuração no n8n:

• Base URL: https://app.chatwoot.com (ou sua instância)
• Access Token: Cole o token copiado
• Account ID: ID da sua conta (geralmente na URL)

2. Client API

Use para interfaces de chat customizadas.

Como obter:

1. No Chatwoot, vá em Settings → Inboxes
2. Selecione uma inbox do tipo API
3. Em Configuration, copie o Inbox Identifier
4. Crie um contato via API, receberá o Contact Identifier

Configuração no n8n:

• Base URL: https://app.chatwoot.com (ou sua instância)
• Inbox Identifier: Identificador da inbox
• Contact Identifier: Identificador do contato

3. Platform API

Use para gerenciamento administrativo (apenas self-hosted).

Como obter:

1. Acesse o Super Admin Console
2. Vá em Platform Apps
3. Crie um novo Platform App
4. Copie o Access Token gerado

Configuração no n8n:

• Base URL: URL da sua instância self-hosted
• Platform Access Token: Token do Platform App

🎨 Recursos Disponíveis

Application API - Exemplos

Contacts (Contatos)

// Buscar todos os contatos
Operation: Get All
Page: 1
Sort: name

// Criar novo contato
Operation: Create
Name: João Silva
Email: [email protected]
Phone: +5511999999999

// Buscar contato específico
Operation: Get
Contact ID: 123

// Atualizar contato
Operation: Update
Contact ID: 123
Name: João Silva Jr.

// Deletar contato
Operation: Delete
Contact ID: 123

// Buscar contatos
Operation: Search
Query: joão

Conversations (Conversas)

// Listar conversas
Operation: Get All
Status: open
Inbox ID: 1

// Criar conversa
Operation: Create
Contact ID: 123
Inbox ID: 1

// Buscar conversa específica
Operation: Get
Conversation ID: 456

// Alternar status
Operation: Toggle Status
Conversation ID: 456
Status: resolved

Messages (Mensagens)

// Listar mensagens de uma conversa
Operation: Get All
Conversation ID: 456

// Criar mensagem
Operation: Create
Conversation ID: 456
Content: Olá! Como posso ajudar?
Message Type: outgoing
Private: false

// Criar mensagem com anexo
Operation: Create
Conversation ID: 456
Content: Aqui está o arquivo
Attachments: [binary data]

Webhooks

// Listar webhooks
Operation: Get All
Account ID: 1

// Criar webhook
Operation: Create
Webhook URL: https://seu-webhook.com/chatwoot
Events: ["conversation_created", "message_created"]
HMAC Secret: seu-secret-aqui

// Atualizar webhook
Operation: Update
Webhook ID: 789
Events: ["conversation_created", "message_created", "conversation_resolved"]

// Deletar webhook
Operation: Delete
Webhook ID: 789

Client API - Exemplos

// Criar contato (Client API)
Resource: Contacts
Operation: Create
Name: Maria Santos
Email: [email protected]
Phone: +5511888888888

// Criar conversa
Resource: Conversations
Operation: Create
Contact Identifier: contact_xyz

// Enviar mensagem
Resource: Messages
Operation: Create
Conversation ID: 123
Content: Olá, preciso de ajuda!

Platform API - Exemplos

// Criar conta (Platform API)
Resource: Accounts
Operation: Create
Name: Empresa ABC
Locale: pt_BR

// Criar usuário
Resource: Users
Operation: Create
Name: Admin User
Email: [email protected]
Password: senha-segura

// Adicionar usuário à conta
Resource: Account Users
Operation: Create
Account ID: 10
User ID: 50
Role: administrator

💡 Exemplos de Uso

Workflow 1: Notificação de Nova Conversa

Trigger: Chatwoot Webhook (conversation_created)
↓
Chatwoot Node: Get Contact (Application API)
↓
Slack Node: Send Message

Workflow 2: Resposta Automática

Trigger: Chatwoot Webhook (message_created)
↓
IF Node: message.message_type === 'incoming'
↓
OpenAI Node: Generate Response
↓
Chatwoot Node: Create Message (Application API)

Workflow 3: Criar Contato e Iniciar Conversa

Trigger: HTTP Request / Form Submission
↓
Chatwoot Node: Create Contact (Application API)
↓
Chatwoot Node: Create Conversation (Application API)
↓
Chatwoot Node: Create Message (Application API)

Workflow 4: Relatório Diário

Trigger: Cron (todos os dias 9h)
↓
Chatwoot Node: Get Reports - Conversations (Application API)
↓
Function Node: Process Data
↓
Email Node: Send Report

🔧 Troubleshooting

Erro: "401 Unauthorized"

Causa: Token inválido ou expirado

Solução:

1. Verifique se o token está correto
2. Gere um novo token no Chatwoot
3. Atualize as credenciais no n8n

Erro: "404 Not Found"

Causa: ID de recurso não existe ou URL base incorreta

Solução:

1. Verifique o ID do recurso (contact, conversation, etc.)
2. Confirme a Base URL nas credenciais
3. Teste o endpoint via browser/Postman

Erro: "401 Non permissible resource" (Platform API)

Causa: Platform App não tem permissão para acessar o recurso

Solução:

1. Acesse o Rails console da sua instância
2. Execute:

PlatformAppPermissible.create!(
  platform_app: PlatformApp.find(1), 
  permissible: Account.find(1)
)

Erro: "422 Unprocessable Entity"

Causa: Dados inválidos na requisição

Solução:

1. Verifique os campos obrigatórios
2. Valide o formato dos dados (email, phone, etc.)
3. Consulte a documentação oficial

Paginação não funciona

Solução:

• Use o parâmetro page com números >= 1
• Verifique o campo meta na resposta para info de páginas

Documentação desatualizada

Se encontrar discrepâncias entre a documentação e o comportamento real:

1. Abra o DevTools do browser (F12)
2. Vá na aba Network
3. Execute a operação no Chatwoot UI
4. Veja o request real (payload, headers, URL)
5. Replique no n8n
6. Abra uma issue para atualizarmos

👨‍💻 Desenvolvimento

Setup Local

# Clone o repositório
git clone https://github.com/yurisilva/chatwoot-community-nodes.git
cd chatwoot-community-nodes

# Instale dependências
npm install

# Build
npm run build

# Link localmente
npm link

# No diretório do n8n
npm link n8n-nodes-chatwoot-complete

Estrutura do Código

nodes/Chatwoot/
├── Chatwoot.node.ts              # Node principal
├── GenericFunctions.ts           # Helpers HTTP
├── ApplicationApi/               # Application APIs
│   ├── Contacts/
│   │   └── index.ts
│   ├── Conversations/
│   └── ...
├── ClientApi/                    # Client APIs
└── PlatformApi/                  # Platform APIs

Comandos Úteis

npm run lint          # Verificar código
npm run format        # Formatar código
npm run build         # Compilar TypeScript
npm run dev           # Watch mode

🤝 Contribuindo

Contribuições são muito bem-vindas!

Como Contribuir

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Diretrizes

• Siga os padrões de código TypeScript
• Mantenha arquivos com max 200-300 linhas
• Adicione testes para novas funcionalidades
• Atualize a documentação
• Escreva commits claros e objetivos

📚 Referências

Documentação Oficial

• Chatwoot API Reference
• n8n Creating Nodes
• n8n Community Nodes

Links Úteis

• Chatwoot GitHub
• n8n GitHub
• Chatwoot Community

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

👤 Autor

Yuri Silva

• GitHub: @yurisilva
• Email: [email protected]

🙏 Agradecimentos

• Equipe Chatwoot pela excelente API e documentação
• Comunidade n8n pelo suporte e ferramentas
• Projetos existentes que serviram de inspiração:
  • sufficit/n8n-nodes-chatwoot
  • pixelinfinito/n8n-nodes-chatwoot

📊 Status do Projeto

Cobertura Atual

| API Type | Recursos | Status | |----------|----------|--------| | Application APIs | 10/20 | ✅ Versão 1.0.0 | | Client APIs | 3/3 | ✅ Versão 1.0.0 | | Platform APIs | 4/4 | ✅ Versão 1.0.0 |

Roadmap

• [x] Planejamento e arquitetura
• [x] Fase 1: Setup e credenciais
• [x] Fase 2: Application APIs - Core
• [x] Fase 5: Client APIs
• [x] Fase 6: Platform APIs
• [x] Fase 7: Qualidade e documentação
• [x] Fase 8: Publicação no npm ✅
• [ ] Fase 3: Application APIs - Complementares (próxima versão)
• [ ] Fase 4: Application APIs - Avançadas (próxima versão)

🔄 Changelog

[1.0.0] - 2026-01-19

• ✅ Primeira versão estável publicada
• ✅ 10 recursos da Application API
• ✅ 3 recursos da Client API
• ✅ 4 recursos da Platform API
• ✅ Logo/ícone otimizado
• ✅ Documentação completa
• ✅ Publicado no npm

[0.1.0-beta.1] - 2026-01-19

• Versão beta inicial
• Estrutura do projeto
• Documentação base

Feito com ❤️ por Yuri Silva

Se este projeto te ajudou, considere dar uma ⭐!