Description

n8n-nodes-crmax

!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 lastincomingmessage_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 INVALIDCONTACTID (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: lastincomingmessage_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