n8n-nodes-crmax

Nó customizado para integração do CRMax CRM com n8n.

Sobre o CRMax

CRMax é um CRM de gestão de leads via WhatsApp com integração Meta/Google Ads, pipelines de vendas, métricas em tempo real e IA para análises.

Instalação

Community Nodes (recomendado)

No n8n: Settings > Community nodes > Install e informe:

n8n-nodes-crmax

Self-hosted via npm

cd ~/.n8n/nodes
npm install n8n-nodes-crmax

Depois reinicie o n8n.

Configuração

1. No n8n, vá em Credentials > New
2. Procure por CRMax API
3. Preencha:
   • API Token: Token gerado em CRMax > Configurações > API Tokens (formato: crmax_xxx)
   • Base URL: https://painel.crmax.com.br (ou sua instância)
   • Organization ID: UUID da sua organização

Recursos Disponíveis

📋 Cards (Leads)

Operação	Descrição
Create	Criar novo card no pipeline
Get	Obter card por ID
Get Many	Listar cards com filtros
Update	Atualizar card
Archive	Arquivar/desarquivar card
Move Stage	Mover card para outra etapa
Delete	Excluir card
Add Note	Adicionar anotação
Get Notes	Listar anotações

👤 Contacts

Operação	Descrição
Create	Criar contato
Get	Obter por ID
Get by Phone	Obter por telefone
Get Many	Listar contatos
Update	Atualizar contato
Update by Phone	Atualizar por telefone
Batch Create/Update	Criar/atualizar em massa
Update Tags	Atualizar tags
Update Custom Fields	Atualizar campos personalizados
Add Note / Get Notes / Update Note / Delete Note	Anotações do contato

💬 Messages

Operação	Descrição
Send Text by Session	Enviar texto para uma sessão existente
Send Text by Phone	Enviar texto para um telefone, via canal escolhido
Send File by Session	Enviar imagem/áudio/documento para uma sessão
Send File by Phone	Enviar arquivo para um telefone
Send Template by Conversation	Enviar template aprovado numa conversa existente (Cloud API)
Send Template by Phone	Enviar template para um telefone, criando contato e conversa se não existirem (Cloud API)
Get Status	Obter status de entrega da mensagem

📨 Templates (Meta WhatsApp)

Templates são o único jeito de falar com um lead fora da janela de 24 horas. Só funcionam em canais Cloud API.

Operação	Descrição
Get Many	Listar templates da organização (filtros por status e categoria)
Get	Obter template por ID
Create	Criar template (fica como rascunho)
Update	Atualizar template — lê o atual antes de salvar, para não apagar cabeçalho e rodapé
Delete	Excluir template
Submit	Enviar para aprovação da Meta
Sync	Puxar da Meta o status atual dos templates

Cabeçalho de mídia: imagem, vídeo e documento no cabeçalho precisam ser enviados pelo painel do CRMax. Uma URL pública colocada no Header Content é recusada pela Meta na aprovação.

🗨️ Conversations

Operação	Descrição
Lookup by Phone	Achar contato e conversas por telefone, sem criar nada. Devolve last_incoming_message_at
Start	Abrir (ou reaproveitar) conversa num canal, sem enviar mensagem
Assign	Atribuir conversa a um atendente e/ou equipe
Transfer	Transferir conversa
Toggle AI	Pausar/retomar o agente de IA na conversa
Add Note / Get Notes / Update Note / Delete Note	Anotações internas

👥 Users

Operação	Descrição
List	Listar usuários da organização
Get	Obter usuário por ID

🎯 Sessions (Helena-style API)

Operação	Descrição
Get by Contact	Sessões de um contato pelo contactId, da mais recente para a mais antiga
Get Many	Listar sessões (filtros: status, contato, conversa, canal, offset)
Get	Obter sessão
Update	Atualizar sessão
Get Messages	Obter mensagens da sessão (com limit/offset)
Send Text	Enviar texto via sessão
Close	Fechar sessão
Transfer	Transferir sessão

Fluxo canônico — do telefone até responder na sessão:

Contact > Get by Phone → Session > Get by Contact (Latest Only + Status Open) → Session > Send Text

Dois detalhes que costumam parecer bug:

• Sessão só existe depois que o contato manda pelo menos uma mensagem. Contato criado por importação ou pela API não tem sessão nenhuma, e a busca devolve lista vazia — não é erro.
• Um contato que fala por dois canais tem uma sessão aberta por canal. Use o campo Channel ID para escolher qual.

O campo Contact ID espera o UUID do contato, não o telefone. Mandar telefone devolve 400 INVALID_CONTACT_ID (requer a API do CRMax atualizada; em API antiga o mesmo caso volta como 500).

Cuidado ao mapear o ID. Contact > Get by Phone devolve o contato flat, então {{ $json.id }} funciona. Já Conversation > Lookup by Phone devolve aninhado: o ID está em {{ $json.contact.id }}, não em $json.contactId. Se a expressão resolver para vazio, o nó agora falha com erro explícito em vez de devolver a sessão de outro contato.

📊 Pipelines

Operação	Descrição
Get Many	Listar pipelines
Get	Obter pipeline
Get Custom Fields	Listar campos personalizados
Create Custom Field	Criar campo personalizado

🔗 Webhooks

Operação	Descrição
Create	Criar webhook
Get Many	Listar webhooks
Get	Obter webhook
Update	Atualizar webhook
Delete	Excluir webhook
Test	Testar webhook
Get Deliveries	Ver histórico de entregas
Retry Delivery	Reenviar entrega falhada

Exemplos de Uso

Criar lead automaticamente

Trigger: Webhook (recebe dados do formulário)
    ↓
CRMax: Create Card
    - Pipeline ID: {{$json.pipelineId}}
    - Stage ID: {{$json.stageId}}
    - Title: {{$json.nome}}
    - Phone: {{$json.telefone}}
    - Origin: "Formulário Site"

Enviar mensagem de boas-vindas

Trigger: CRMax Webhook (lead.created)
    ↓
CRMax: Message > Send Text by Phone
    - Phone: {{$json.contact.phone}}
    - Instance ID: {{$json.instanceId}}
    - Message: "Olá {{$json.contact.name}}! Obrigado pelo contato..."

Falar com o lead respeitando a janela de 24 horas

Fora das 24 horas desde a última mensagem recebida, o WhatsApp só aceita template.

CRMax: Conversation > Lookup by Phone
    - Phone: {{$json.telefone}}
    ↓
IF: last_incoming_message_at nas últimas 24h?
    ↓ Sim                              ↓ Não
CRMax: Message >                   CRMax: Message >
  Send Text by Phone                 Send Template by Phone

Prefira Send Template by Phone: ele acha ou cria a conversa aberta sozinho.
O Lookup by Phone devolve conversas abertas e fechadas — se for usar
Send Template by Conversation, escolha uma cujo status seja open, senão a
resposta do lead cai numa thread nova, separada do template.

Mover card após resposta

Trigger: CRMax Webhook (message.received)
    ↓
IF: Primeira mensagem?
    ↓ Yes
CRMax: Move Stage
    - Card ID: {{$json.cardId}}
    - Stage ID: "uuid-da-etapa-respondeu"

Eventos de Webhook Disponíveis

• message.received - Mensagem recebida
• message.sent - Mensagem enviada
• lead.created - Lead criado
• lead.updated - Lead atualizado
• lead.moved - Lead movido de etapa
• session.new - Nova sessão
• session.complete - Sessão finalizada
• deal.won - Negócio ganho
• deal.lost - Negócio perdido
• E mais 17 eventos...

Suporte

• Documentação API: https://painel.crmax.com.br/api/reference
• Email: contato@crmax.com.br

Licença

MIT