Manual do Usuário — Comercializ.ai

Plataforma SaaS de pré-vendas com chatbot IA, CRM e WhatsApp integrado. Versão do manual: 2026-04-12

Índice

1. Visão Geral
2. Primeiro Acesso (Onboarding)
3. Bot IA — Configuração Completa
4. Bot IA — Operação Diária
5. CRM — Funil e Leads
6. Campanhas e Automação
7. Relatórios e Integrações
8. Configurações da Conta
9. Administração (Super Admin)
10. Limites por Plano
11. Glossário
12. FAQ

1. Visão Geral

O Comercializ.ai substitui uma equipe de SDRs (pré-vendedores) por um motor de IA que atende, qualifica e pontua leads 24/7 via WhatsApp e widget no site. A plataforma inclui:

• Bot IA multi-provedor (OpenAI, Claude, Gemini, Grok)
• CRM visual com pipeline Kanban e score automático
• Campanhas de email com geração de conteúdo por IA
• Cadências automáticas multi-canal (email → WhatsApp → email)
• Grupos de leads e envio em massa
• Relatórios com 8 dashboards e exportação em PDF

Papéis (roles)

2. Primeiro Acesso (Onboarding)

Ao se cadastrar, você passa por 4 passos obrigatórios:

Passo 1 — Escolha seu modelo (/onboarding/template)

Selecione um dos templates de indústria (Imobiliário, Saúde, Tecnologia, Educação, Automotivo, Jurídico, Varejo ou Padrão). O template define:

• System prompt base do bot
• Regras de score (eventos que aumentam pontuação)
• Tipos de perfil e de material
• Palavras-chave de handoff (transferência para humano)

Dica: Sempre dá para trocar depois em Configuração → Config Bot → Perfil do Negócio.

Passo 2 — Revise seu bot (/onboarding/bot)

Duas caixas vêm pré-preenchidas pelo template:

• Persona: nome do "atendente virtual" (ex: Rogério, Ana, Dra. Júlia)
• Mensagem de abertura: primeira resposta do bot. Use {persona} e {{nome}} como variáveis.
• Contexto do negócio: descrição do produto/serviço. A IA usa isso para responder dúvidas.

Passo 3 — Conecte o WhatsApp (/onboarding/whatsapp)

Escaneie o QR Code com o WhatsApp Business do número que vai atender os leads. O sistema valida a conexão em tempo real.

Importante: use um número dedicado — o bot vai responder automaticamente toda mensagem que chegar.

Passo 4 — Escolha o plano (/onboarding/plan)

Trial de 14 dias sem cartão. Após o trial, escolha Starter, Pro ou Business.

3. Bot IA — Configuração Completa

Menu: Configuração → Config Bot (/crm/bot/settings)

Esta é a tela mais importante da plataforma. Cada seção controla um aspecto do comportamento do bot.

3.1 Perfil do Negócio

Template atual do bot. Mostra ícone, nome e descrição.

• Trocar Perfil: abre um grid com todos os templates disponíveis. Ao escolher outro, você decide:
  • Resetar para padrão: substitui TODAS as configs (mensagens, score, persona) pelas do novo template
  • Manter configs: só troca as regras estruturais (stages, score rules), mantém suas mensagens

Use "manter configs" se já customizou bastante e só quer migrar entre templates parecidos.

3.2 Persona do Bot

Nome do "atendente virtual" que aparece nas mensagens. Ex: "Olá! Sou o Rogério, consultor do…"

3.3 Mensagens Principais

Três textareas essenciais:

Boas práticas:

• Abertura curta (1-2 linhas), terminando com uma pergunta
• Contexto detalhado (pode ter 500+ palavras) — quanto mais a IA souber, melhor responde
• Evite "scripts rígidos" no contexto; prefira princípios ("sempre ofereça agendamento após qualificar orçamento")

3.4 Inteligência Artificial

Controla o comportamento conversacional da IA:

• Estilo da conversa:
  • v2 — Amigável (padrão): tom próximo, descontraído, usa emojis com moderação
  • v1 — Profissional: formal, sem emojis, respostas mais curtas
• Histórico considerado: quantas mensagens anteriores a IA lê antes de responder (5-50). Mais histórico = mais contexto, mais custo por resposta. Padrão: 10.
• Max caracteres por resposta: limite de tamanho da resposta (100-2000). Padrão: 600. WhatsApp fica estranho acima de 1200.
• Temperatura: criatividade (0-1). 0 = respostas previsíveis e factuais; 1 = mais criativo, pode inventar. Padrão: 0.7.
• A/B Testing: divide leads em dois grupos — um conversa com IA, outro com fluxo estático. Ative e defina o % que usa IA (1-100).

Guardrails (sempre ativos)

O bot tem proteções automáticas que você não precisa configurar:

• Anti-repetição: não repete a mesma resposta em sequência
• Detecção de loop: se a conversa travar, troca de abordagem
• Timeout 15s: se a IA demorar, responde com mensagem neutra
• Rate limit 2s/msg: não envia mais rápido que isso (evita ban do WhatsApp)
• Cooldown: não reinicia conversa se lead responder dentro de 30min / 2h / 8h
• Classificador de intenção: detecta se o lead quer agendar, pedir material, falar com humano
• Fallback: se a IA falhar, cai numa resposta segura pré-configurada

3.5 Atendentes (para handoff)

Lista de pessoas que recebem os leads transferidos. Cada linha:

• Nome
• Telefone (formato: +55 21 99999-9999)
• Email

Recebem notificação por WhatsApp + email quando um lead é transferido. Você pode adicionar vários (o sistema distribui em rodízio).

3.6 Regras de Score

Eventos que aumentam a pontuação do lead. Vêm do template, mas são editáveis em Admin → Templates (Super Admin) ou Admin → Organização → System Prompt Custom.

Faixas padrão:

• Frio: 0-20 pontos
• Morno: 21-49 pontos
• Quente: 50+ pontos (auto-handoff opcional)

Exemplos de eventos:

3.7 Configurações avançadas

Geralmente editadas uma vez e esquecidas:

• reply_delay_seconds: delay em segundos antes do bot responder (deixa mais humano). Padrão: 2.
• auto_handoff_hot: se ligado, lead com score ≥ 50 é automaticamente transferido para atendente.
• auto_reset_hours: horas de inatividade antes de resetar a conversa (ex: 72h → conversa velha, reinicia do zero).
• Modo do WhatsApp (em "WhatsApp & Handoff"): controla quem o bot responde no WhatsApp conectado. Três opções:
  • Responder todos — o bot responde qualquer mensagem recebida. Recomendado para números dedicados ao bot.
  • Somente iniciados — o bot só responde leads que receberam antes uma mensagem sua (envio massivo ou manual). Recomendado para números compartilhados com atendimento humano.
  • Não responder — bot desativado no WhatsApp; as mensagens chegam mas não há resposta automática.
• calendar_external_url: se preenchido, o bot envia esse link em vez de oferecer slots próprios.
• llm_provider / llm_model / llm_api_key: se quiser usar sua própria conta OpenAI/Claude/etc. Deixe vazio para usar a infraestrutura Comercializ.
• llm_system_prompt_webchat: prompt diferente para o widget do site (opcional).

Quem responde — todos os contatos ou só iniciados? O bot responde a toda mensagem recebida no WhatsApp conectado, exceto:

• Contatos marcados com bot_enabled = false (editar lead → desligar bot)
• Leads em estado aguardando_humano após handoff
• Durante cooldown pós-handoff (definido em auto_reset_hours)

4. Bot IA — Operação Diária

4.1 Bot Dashboard — Automação → Bot Dashboard (/crm/bot)

Resumo em cards:

• Leads totais — base toda
• Conversas (hoje) — mensagens recebidas nas últimas 24h
• Pendentes — leads aguardando resposta humana (handoff não atendido)
• Score quente — leads prontos para fechamento
• Gráfico de atividade (mensagens/dia nos últimos 7 dias)

4.2 Leads / Conversas — Principal → Leads / Conversas (/crm/bot/leads)

Busca e filtros

• Busca textual: nome, telefone, email, origem
• Filtro por score: todos / frio / morno / quente
• Filtro por status: ativo / aguardando humano / transferido
• Filtro por origem: manual, planilha, site, WhatsApp, etc.

Tabela

Colunas: checkbox, nome, telefone, origem, perfil, objetivo, score (com badge colorido), status, estado, ações (ver, editar, deletar).

Ações em massa (checkbox + botão)

• Mover para lixeira (soft delete — recuperável)
• Deletar definitivo (irrecuperável, pede confirmação)

Importar CSV

• Arquivo com colunas name, email, phone (obrigatórias)
• Deduplicação automática por telefone
• Upload em lotes de 50 por vez
• Relatório final: criados, atualizados, ignorados

Criar lead manualmente

Campos: nome, telefone (auto-formatado), email (opcional), origem, bot_enabled (liga/desliga bot para esse lead específico).

Exportar CSV

Exporta os leads filtrados (respeita os filtros ativos). Colunas dinâmicas conforme template (ex: template imobiliário inclui "metragem").

4.3 Detalhe do Lead — clique no lead em Principal → Leads / Conversas (/crm/bot/leads/:id)

Tela completa com:

Cabeçalho

• Nome, telefone, origem
• Score (badge) e status (badge)
• Botões rápidos:
  • Contato Direto (+25 pts automáticos) — marca que o lead ligou/chamou diretamente
  • Enviar Material — modal com lista de materiais ativos
  • Agendar Reunião — date picker + observações
  • Transferir — abre modal com motivo
  • Nota — adicionar observação livre
  • Reset (âmbar) — limpa conversa e reinicia
  • Limpar (vermelho) — zera score e estado

Painel esquerdo — Dados do Lead

Editáveis inline:

• Email, telefone, objetivo, perfil, "deseja contato"
• Ação mais recente
• Timeline de score (cronologia de eventos que somaram pontos)

Painel direito — Timeline da conversa

Cronologia completa: mensagens trocadas, eventos de score, visitas, handoffs, notas. Cada item com data/hora.

Chat direto

Ao expandir, você pode enviar mensagem manualmente para o lead pelo WhatsApp conectado. Útil para quando o lead chega no WhatsApp sem responder ao bot.

4.4 Envio em Massa — Mensagens → Enviar Mensagem (/crm/bot/send)

Disparar mensagem para vários leads:

1. Filtrar (por score, status, origem)
2. Ver preview da quantidade selecionada
3. Escrever mensagem com variáveis {{nome}}, {{telefone}}, {{empresa}}
4. Agendar (agora ou data/hora futura)
5. Enviar

Após envio: relatório com total enviado, sucesso, falha, agendados.

Cuidado: WhatsApp pode banir números que enviam muitas mensagens massivas sem interação prévia. Use com moderação e sempre para leads que já interagiram.

4.5 Materiais — Automação → Materiais (/crm/bot/materials)

Arquivos que o bot pode enviar: PDFs, vídeos, mapas, tabelas de preço.

• Criar: nome, tipo, URL externa ou upload direto (máx. 50 MB)
• Categoria: para organizar (ex: "Apresentação institucional", "Tabela de preços")
• Ativo: se desligado, o bot não envia esse material
• Grid de estatísticas: total por tipo (pdf/vídeo/mapa/tabela)

Limite Free: 2 materiais. Tentar criar o 3º abre paywall.

5. CRM — Funil e Leads

5.1 Dashboard — Principal → Dashboard (/crm)

• Cards: leads ativos, conversas hoje, leads quentes, oportunidades
• Gráficos: pipeline por estágio, atividade 7d, top origens

5.2 Funil de Vendas — Principal → Funil de Vendas (/crm/pipeline)

Visualização Kanban dos leads por estágio:

START → QUALIFICATION → MATERIAL_SENT → VISIT_SCHEDULED → HANDOFF

• Drag & drop entre colunas move o lead de estágio
• Cada card mostra: nome, score, origem, ações rápidas

6. Campanhas e Automação

6.1 Campanhas de Email — Mensagens → Campanhas de Email (/crm/campaigns)

Campanhas de email com geração por IA:

• Criar: nome, descrição, leads-alvo (grupo ou filtro), mensagem de boas-vindas, dia/hora de início
• IA gera o email: descreva o objetivo → IA cria assunto + HTML
• Tracking de abertura: pixel invisível conta aberturas e adiciona pontos ao score
• Status: ativa, pausada, concluída

6.2 Cadências — Automação → Cadências (/crm/cadences)

Sequências automatizadas multi-canal:

• Trigger: novo lead, score atingiu X, inscrição manual
• Etapas: enviar email → esperar 2 dias → enviar WhatsApp → esperar 1 dia → enviar outro email
• Ações possíveis: enviar mensagem, agendar, transferir, adicionar a grupo

6.3 Grupos de Leads (/crm/groups, acessível via filtros em Leads / Conversas)

Agrupamentos dinâmicos para segmentar campanhas e cadências:

• Filtros: score, status, origem, objetivo, template
• Salvar o filtro como grupo nomeado
• Reutilizar em múltiplas campanhas

7. Relatórios e Integrações

7.1 Relatórios — Principal → Relatórios (/crm/reports)

8 dashboards interativos:

• Funil de conversão
• Performance por origem
• Performance por atendente
• Receita (leads que viraram clientes)
• Distribuição de score
• Tempo médio de resposta
• Taxa de handoff
• Evolução semanal

Exportar: PDF (via geração client-side) ou CSV.

7.2 Integrações — Configuração → Integrações (/crm/integrations)

• Meta Ads (Lead Ads → lead no CRM)
• Google Ads (import de formulário)
• RD Station
• Telegram
• Instagram DM
• Webhooks (URL customizada recebe eventos)

Cada integração: status, última sincronização, botão desconectar/reconectar.

7.3 WhatsApp — Configuração → WhatsApp (/crm/whatsapp)

• Status da conexão
• Log de mensagens (entrada/saída)
• Reconectar se cair (novo QR Code)

8. Configurações da Conta

Menu: Configuração → Conta & Equipe (/crm/settings)

Dados da organização

• Nome, logo, website, telefone principal

Plano e cobrança — item Plano na sidebar (/crm/billing)

• Plano atual + uso do mês (leads usados / limite)
• Upgrade/downgrade (efeito imediato, cobrança proporcional)
• Método de pagamento (cartão, PIX, boleto via Asaas)
• Histórico de faturas

Membros

• Listar, convidar, remover, alterar papel
• Toggle 2FA por usuário

Segurança

• 2FA (TOTP)
• API Keys (para integrações externas)

9. Administração (Super Admin)

Esta área é interna Comercializ. Se você é cliente, pule esta seção.

Rota base: /admin/*

9.1 Dashboard (/admin)

KPIs globais: MRR, orgs pagantes, total de orgs, churn (30d), leads, mensagens, usuários, orgs em trial. Gráficos: MRR 12 meses, funil de conversão, signups por semana, distribuição de planos. Tabela top 10 orgs por leads. Métricas operacionais: tempo médio de resposta do bot, mensagens por período, taxa de handoff, requests LLM, custo LLM, erros, leads stuck.

9.2 Organizações (/admin/orgs)

Lista todas com busca por nome/slug/email, filtro de status (ativo, trial, suspenso, cancelado). Paginação 20/pág.

9.3 Detalhe da Organização (/admin/orgs/:id)

• Cards: status, membros, leads, mensagens
• Alterar status: ativo / trial / suspenso / cancelado
• Alterar plano: dropdown com preço e max leads
• System Prompt Custom — sobrescreve o template. Deve conter:
  1. Persona e objetivo
  2. Regras de conversa (tom, tamanho)
  3. Ações disponíveis (send_material, schedule_visit, transfer_human, check_availability)
  4. Regra crítica de agendamento
  5. Qualificação (usa {score_events_list})
  6. Memória a extrair (nome, empresa, cargo, orçamento)
  7. Formato JSON de saída (text, action, score_events, detected_profile, detected_objective, detected_area, memory)
• Gerador de Prompt com IA: escreva um rascunho em linguagem natural, escolha provider, clique "Adaptar com IA" para formatar nos 7 blocos acima.

9.4 Usuários (/admin/users)

Busca por nome/email/org. Editar: nome, email, role, plano, nova senha, verificado. Reset de senha (diálogo). Delete (com aviso especial se owner — apaga a org inteira).

9.5 Templates (/admin/templates)

Grid de cards com badges (Custom / Builtin / Inativo). Criar template custom: slug, label, descrição, ícone.

9.6 Detalhe do Template (/admin/templates/:id)

Abas:

• Geral: label, descrição, ícone, toggle ativo
• Mensagens: profile types (value/label), material types (value/label/ícone)
• System Prompt: textarea com help de variáveis ({persona}, {score_events_list}, {context}), botão Testar (envia msg, retorna resposta + tokens)
• Score Rules: lista de eventos + pontos + label
• Handoff Keywords: palavras que disparam transferência automática

9.7 Prompts (/admin/prompt)

Visão consolidada: thresholds (frio/morno/quente), prompt e score rules por template. Salvar / Restaurar padrão.

9.8 LLM (/admin/llm)

Configuração dos provedores de IA:

• Free Tier e Paid Tier (cards com status)
• Campos: provider (OpenAI / Anthropic / DeepSeek / Groq / OpenRouter), model, API key, max tokens/tenant (-1 = ilimitado), descrição
• Dashboard de uso: total requests, input/output tokens, custo. Tabela por tenant. Trend chart.

9.9 Email SMTP (/admin/email)

Configuração global para emails transacionais e campanhas:

• Host, porta (465 SSL / 587 TLS), toggle secure, user, senha, from
• Botão Testar: envia email de teste para endereço informado

9.10 Auditoria (/admin/audit)

Log imutável de ações: data/hora, ação, recurso+ID, usuário, org, IP, detalhes (JSON). Busca por ação/email/org/IP. Paginação 30/pág.

9.11 Operações (/admin/ops)

Monitoramento em tempo real (auto-refresh 30s):

• Health banner: status + checks (API ms, LLM error%, leads stuck)
• Sandbox demo: toggle para habilitar envio de demo no WhatsApp após signup
• Content moderation: flags abertas (severity, matched_terms), ações Revisar / Dispensar / Suspender org
• KPIs: tempo de resposta, msgs (hoje/24h/7d), handoffs 7d, leads ativos
• Gráficos: msgs/hora (24h), classificação, leads por canal

9.12 Email Spool (/admin/email-spool)

Fila de emails: para, assunto, status, data, retries. Ações: retry, deletar.

9.13 WhatsApp Business (/admin/whatsapp)

Configuração da API oficial Meta: Business Account ID, Access Token, Phone Number ID. Status e teste.

10. Limites por Plano

Trial: 14 dias grátis em qualquer plano, sem cartão de crédito.

11. Glossário

12. FAQ

O bot responde a qualquer contato no WhatsApp? Sim, exceto se o lead tiver bot_enabled = false, estiver aguardando_humano ou em cooldown pós-handoff.

Posso usar minha própria conta OpenAI/Claude? Sim. Vá em Configuração → Config Bot → seção "Avançado" e preencha llm_provider, llm_model e llm_api_key. Deixe vazio para usar a infraestrutura Comercializ (incluída no plano).

O que acontece se eu exceder o limite de leads do plano? Você recebe notificação aos 80% do limite. Novos leads ainda entram, mas o bot não responde até você fazer upgrade. Leads existentes não são removidos.

Posso ter dois números de WhatsApp na mesma org? Só no plano Business. Starter e Pro usam um número por organização.

Meus dados são exportáveis? Sim, a qualquer momento, mesmo após cancelar. Vá em Principal → Leads / Conversas → "Exportar CSV", e em Principal → Relatórios → "Exportar".

A IA aprende com meus dados? Não. Suas conversas não treinam modelos. O bot lê apenas o contexto e o histórico da conversa atual a cada resposta.

Como desligo o bot temporariamente? Vá em Configuração → Config Bot, seção "WhatsApp & Handoff", e em "Modo do WhatsApp" escolha "Não responder". As mensagens continuam chegando, mas o bot não responde automaticamente.

Se quiser que o bot só responda quem você já iniciou conversa (útil em números compartilhados com atendimento humano), escolha "Somente iniciados".

Para voltar ao atendimento completo, escolha "Responder todos".

O trial consome meu limite de leads? Sim. Durante os 14 dias, você tem o limite do plano que escolher.

Posso testar um novo system prompt sem quebrar a produção? Vá em Configuração → Config Bot → seção "Inteligência Artificial" → ative A/B Testing. Defina, por exemplo, 20% — apenas esse percentual de leads conversa com o novo prompt.

Onde vejo quanto gastei com a IA? Super Admin → LLM → Dashboard de uso (tokens e custo por tenant). Para clientes finais, Relatórios → Receita e custos (v1.9+).

Dúvidas? Fale com a gente no WhatsApp (21) 96948-0001 ou em contato@comercializ.ai.