Introdução

Nexus Atendimento 2.0 é um sistema de gerenciamento de clientes multi-empresa para WhatsApp: inbox, CRM, IA com ferramentas, cobrança (Mercado Pago / DePix), portal do cliente, FlowBuilder e API para integrações.

Mapa do menu

Streaming × outros ramos

O painel muda conforme o tipo da empresa:

Onboarding

Checklist em /onboarding com detecção do que já está configurado (canal, IA, equipe, etc.).

Wizard: /onboarding?wizard=1 · Trilhas: Streaming ou Atendimento.

Canais WhatsApp

Em Canais WhatsApp, escolha o provedor:

Inbox

1. Abra Atendimento.
2. Selecione a conversa — badge Transferido quando a IA encaminhou.
3. Responda, anexe imagem/PDF (WhatsApp) ou transfira.
4. Agendamentos e dados do cliente no painel lateral.
5. Finalize quando concluir.

Respostas rápidas (operador)

Menu Atendimento → Respostas rápidas → Nova.

No inbox: botão ⚡ no composer → selecionar → envia no WhatsApp.

IA envia template automaticamente

Desligado por padrão. Ative só com atalhos bem definidos.

1. Crie o template em /respostas-rapidas.
2. /ia/configuracoes → Respostas rápidas automáticas.
3. Ative envio automático e score mínimo 4.

Agente de IA

Provedores em /ia/provedores · Agente em /ia/configuracoes · Base RAG em /ia/base (botão Avaliar qualidade).

FAQ opcional em /configuracoes/faq. Transferência: palavras como humano / atendente.

Variáveis: {link_area_cliente}, {nome_cliente}, {pix1}.

Cobrança e portal do cliente

• Integrações — Mercado Pago / DePix
• Faturas — emissão e links de pagamento
• Portal — login OTP WhatsApp; variável {link_area_cliente}
• Automações — vencimento, atraso, confirmação

Agenda e cobrança por serviço

Para empresas não-streaming (billing_mode = per_service):

• Cadastre serviços e categorias.
• Ao criar agendamento, o sistema pode gerar fatura automaticamente.
• Com appointment_auto_send_billing ativo, envia o link de pagamento no WhatsApp do cliente.

FlowBuilder

Fluxos em /flowbuilder.

• Validação — erros impedem publicar.
• Simulador — testa sem enviar WhatsApp.
• Enviar cobrança (send_billing) — 2ª via com link MP/DePix.

Tutoriais: índice · atendimento · streaming

API REST v1

Base: https://SEU_DOMINIO/api/v1

Autenticação

1. No painel: Integrações → Chaves de API → Nova chave.
2. Copie o token nxz_… (exibido uma vez).
3. Envie em todas as rotas de dados:

Authorization: Bearer nxz_SUA_CHAVE
# ou
X-API-Key: nxz_SUA_CHAVE

Endpoints

limit máximo: 200. Telefone no path: só dígitos com DDI (ex. 5511999999999).

Listar conversas

curl -sS "https://SEU_DOMINIO/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer nxz_SUA_CHAVE"

Enviar mensagem WhatsApp

curl -sS -X POST "https://SEU_DOMINIO/api/v1/conversations/5511999999999/messages" \
  -H "Authorization: Bearer nxz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"text":"Olá! Como posso ajudar?"}'

Listar / detalhar clientes

curl -sS "https://SEU_DOMINIO/api/v1/clients?limit=50" \
  -H "Authorization: Bearer nxz_SUA_CHAVE"

curl -sS "https://SEU_DOMINIO/api/v1/clients/15" \
  -H "Authorization: Bearer nxz_SUA_CHAVE"

JavaScript

const API = "https://SEU_DOMINIO/api/v1";
const KEY = process.env.NEXUS_API_KEY;

const res = await fetch(`${API}/conversations/${phone}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text }),
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();

Erros HTTP

Webhooks outbound

Em Integrações → Webhooks: informe URL HTTPS, evento e (opcional) secret.

O Nexus envia POST com JSON. Responda 200 rápido; use idempotência.

Eventos

Envelope

{
  "event": "message.in",
  "timestamp": "2026-09-04T12:00:00.000Z",
  "company_id": 1,
  "data": {
    "phone": "5511999999999",
    "message_id": "123",
    "type": "text",
    "text": "Oi",
    "conversation_id": "42"
  }
}

payment.confirmed (data)

{
  "invoice_id": 88,
  "client_id": 15,
  "client_name": "Maria",
  "amount": 49.9,
  "payment_date": "2026-09-04",
  "payment_id": 501
}

transfer.human (data)

{
  "phone": "5511999999999",
  "source": "transferir_para_humano",
  "reason": "Cliente pediu atendente",
  "conversation_id": 42
}

Assinatura (opcional)

Se configurar secret, o header vem assim:

X-Nexus-Signature: sha256=<hmac-sha256-hex do body bruto>

Valide com HMAC-SHA256 do body usando o mesmo secret.

Portal do cliente (API pública)

Base: /api/public/portal — não usa API key. Login por OTP no WhatsApp.

Ative o portal em Integrações. Documentação completa também no Swagger (tag Portal).

OpenAPI / Swagger / Postman

A especificação e a UI são públicas (sem chave). Para testar rotas no Swagger, clique em Authorize e cole nxz_….

• Schemas de request/response e erros
• Webhooks com exemplos de payload
• Portal público documentado na mesma spec

No painel: Integrações → botões Swagger / OpenAPI / Postman.

Instalar na VPS (BYO)

1. Contratar plano uso próprio (1 empresa) ou revenda (2+ empresas).
2. Rodar o instalador na VPS e fazer login master.
3. Empresas → Nova empresa → entrar com o login da empresa.
4. Conectar WhatsApp (Meta / UazAPI / Evolution), IA e equipe.