Guia n8n — Evolution + IA

Como consumir a API da NOVIQ Cloud dentro do n8n: IA com memória (RAG) e envio de WhatsApp pela Evolution, com uma única chave.

Base URL e chave

curl -H "Authorization: Bearer $NOVIQ_KEY" https://api.noviqcloud.online/v1/me

Credencial no n8n

Credentials → New → Header Auth

Nos nós HTTP Request: Authentication → Generic Credential Type → Header Auth → NOVIQ API.

IA — POST /v1/ai/chat

POST/v1/ai/chat escopo ai:chat

Não é proxy de LLM cru. Cada chamada passa pelo motor NOVIQ-IA: RAG (Qdrant + full-text), persona e regras do tenant, histórico da conversa, roteador de LLM com fallback automático para o Ollama local, e log de tokens/custo.

{
  "message": "texto do usuário",       // obrigatório
  "model": "groq/openai/gpt-oss-120b", // opcional
  "system": "geral",                   // opcional
  "conversation_id": "uuid",           // opcional — mantém o histórico
  "use_memory": true                   // opcional
}

Resposta:

{
  "conversation_id": "7fe0412f-35ba-46e4-aa44-06258dd997a1",
  "reply": "Sou a NOVIQ IA, assistente virtual oficial da plataforma NOVIQ Cloud.",
  "model": "openai/gpt-oss-120b",
  "tokens": { "in": 413, "out": 87 },
  "memory_hits": 2,
  "system": "geral"
}

No n8n a resposta útil é {{ $json.reply }}. Para continuar a conversa, devolva o conversation_id na próxima chamada.

Nó HTTP Request

Method: POST
URL:    https://api.noviqcloud.online/v1/ai/chat
Body:   JSON
{
  "message": "{{ $json.mensagem }}",
  "model": "groq/openai/gpt-oss-120b"
}
Options → Timeout: 60000

Modelos disponíveis

Regra do roteador: prefixo groq/ vai para o Groq; sem prefixo, para o Ollama local. Se o provedor remoto falhar ou estourar o timeout (40 s), cai sozinho no local — nunca fica sem resposta.

Treinar e memórias

curl -X POST https://api.noviqcloud.online/v1/ai/treinar \
  -H "Authorization: Bearer $NOVIQ_KEY" -H "content-type: application/json" \
  -d '{"title":"Horário de atendimento","content":"Segunda a sexta, 8h às 18h.","kind":"rule"}'

kind: "rule" entra sempre no prompt; kind: "note" só quando o RAG julgar relevante.

WhatsApp — texto e mídia

Use os endpoints da plataforma, não a Evolution crua: a plataforma autentica por tenant, registra uso e mantém a apikey da Evolution fora do n8n.

POST/v1/whatsapp/send-text escopo whatsapp:send

{ "instance": "SUA-INSTANCIA", "number": "5562999999999", "text": "Olá!" }

POST/v1/whatsapp/send-media

{
  "instance": "SUA-INSTANCIA",
  "number": "5562999999999",
  "mediatype": "image",          // image | video | document | audio
  "media": "https://... ou base64",
  "caption": "legenda",
  "fileName": "arquivo.png",
  "mimetype": "image/png"
}

URL pública funciona quando o host não bloqueia o download da Evolution; base64 sempre funciona. audio é enviado como nota de voz.

Instâncias Evolution

O campo instance é o nome da conexão WhatsApp do seu tenant. Criar, ler o QR e gerenciar: painel app.noviqcloud.online → Instâncias (já configura o webhook do n8n sozinho). Instância recém-criada precisa do QR lido antes de enviar — sem isso o retorno é 404 instance does not exist.

Disparar o n8n de fora

POST/v1/automation/webhooks/{path} escopo automation:trigger

Encaminha o corpo para o webhook de produção do n8n, autenticado por API key, acrescentando:

{ "noviq": { "tenantId": "...", "tenantSlug": "...", "keyPrefix": "nvq_live_..." } }

Endereços: editor em https://n8n.noviqcloud.online, webhooks de produção em https://webhooks.noviqcloud.online/webhook/{path}.

Limites e erros

Toda resposta autenticada traz X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-Limit e X-Quota-Used.

Workflow de exemplo

No n8n já existe o workflow “NOVIQ - Exemplo API (IA + WhatsApp)” (importado, inativo). Ele tem dois fluxos:

1. Manual → define mensagem/número/instância → /v1/ai/chat → /v1/whatsapp/send-text.
2. Webhook noviq-demo-ia → /v1/ai/chat → responde o HTTP com a resposta da IA.

Duplique, troque o header pela credencial NOVIQ API e use como base.

NOVIQ Cloud · atualizado em 01/08/2026