1. Visão Geral & Missão do Assistente
Posicionamento, tom de voz e diretrizes de atendimento no WhatsAppO Assistente Virtual da Ferragens Camboatá atua como um verdadeiro vendedor consultivo de balcão no WhatsApp oficial da loja. Sua missão primordial é acolher clientes, tirar dúvidas sobre obras e reformas, consultar o catálogo em tempo real com precisão matemática de preços e orientar sobre as melhores escolhas técnicas.
Venda Consultiva e Eficiência
Ajudar o cliente a encontrar o material certo sem burocracia, sugerir itens complementares essenciais (como fita veda rosca para tubos ou fita isolante para fiação) e acelerar o fechamento de pedidos com retirada na loja física ou entrega rápida.
Tolerância Zero a Alucinações
O bot NUNCA inventa preços, nunca promete produtos que não existem e nunca altera medidas técnicas. Todo valor informado em R$ é extraído diretamente da base oficial de dados.
2. Arquitetura Técnica & Ciclo de Vida
Integração ZapTime, Evolution API v2, Webhooks e LLM com Function CallingA solução roda em infraestrutura otimizada em PHP 8.1 no servidor ZapTime, conectada via Webhook bidirecional à Evolution API v2 para processamento das instâncias do WhatsApp Business e à API da DeepSeek / Grok para raciocínio com chamadas de funções estruturadas (Tool Calling).
Entrada da Mensagem via Webhook
O cliente envia uma mensagem no WhatsApp. O servidor recebe o webhook da Evolution API no endpoint ferragens_bot.php com identificador do cliente (JID), número de telefone e texto puro ou citação de Status.
Filtros de Segurança & Takeover Humano
O script verifica se o cliente está dentro do horário de funcionamento configurado e confere se há atendente humano ativo na tabela zt_human_takeover ou mensagens manuais nos últimos 120 minutos. Se humano estiver ativo, o bot silencia imediatamente.
Raciocínio com LLM e Function Calling
A mensagem é injetada junto ao histórico de até 20 turnos e ao Prompt Mestre. O modelo decide autonomamente se precisa chamar consultar_produto(query) para consultar o catálogo ou notificar_atendente().
Normalização Dimensional & Execução da Busca
O motor em PHP normaliza medidas (ex: 20 amperes → 20A, 3/4 → 25mm, cotovelo → joelho), pontua os produtos por relevância matemática e devolve a lista filtrada para a IA.
Resposta Formatada com Foto Oficial
A IA redige a resposta com preços exatos e anexa a tag [ENVIAR_FOTO: URL] se houver imagem no catálogo. O webhook dispara a foto com legenda via Evolution API e registra a conversa em ferragens_messages.
• Webhook de Produção:
https://zaptime.app.br/ferragens_bot.php• Webhook de Desenvolvimento:
https://dev.zaptime.app.br/ferragens_bot.php• Catálogo Central JSON:
/home/ferragenscamboata.com.br/public_html/wp-content/themes/ferragens-camboata/js/produtos.json• Motor de Busca Front-end:
wp-content/themes/ferragens-camboata/js/main-v2.js (v3.3.4)
3. Guia Mestre de Materiais, Sinônimos & Equivalências
Dicionário comercial de 15 categorias de materiais de construção e ferragensEm lojas de materiais de construção, é comum que o cliente solicite produtos por nomes populares, gírias regionais de obra ou unidades em polegadas (ex: "cano de meia", "cotovelo 3/4", "tomada 20 amperes", "cola maluca", "arame queimado"), enquanto o cadastro do estoque utiliza nomes técnicos. O bot da Camboatá possui um dicionário mestre embutido que equipara termos instantaneamente sem exigir digitação perfeita.
| Categoria | Termo / Gíria do Cliente | Equivalente no Catálogo | Regra Técnica & Aplicação Prática |
|---|---|---|---|
| Elétrica | Tomada 10 Amperes / 10 amp / plugue fino | Tomada 10A (Margirius, Radial, Tramontina) |
Pinos finos (4,0mm). Suporta até 1.270W em 127V / 2.200W em 220V. Indicado para TVs, computadores, luminárias e eletros leves. |
| Elétrica | Tomada 20 Amperes / 20 amp / plugue grosso | Tomada 20A (Margirius, Radial, Tramontina) |
Pinos grossos (4,8mm). Suporta até 2.540W em 127V / 4.400W em 220V. Obrigatório para micro-ondas, air fryer, secadores potentes e cafeteiras. |
| Elétrica | Adaptador 20A para 10A / Benjamim / "T" | Adaptador Para Tomada Bob Esponja (R$ 4,00) |
Permite conectar plugues de 20A em tomadas de 10A. O bot também orienta a substituição segura pelo módulo de tomada 20A. |
| Elétrica | 110V ou 110 Volts | 127V / Residencial Padrão RJ |
110V e 127V referem-se à mesma voltagem residencial monofásica no Rio de Janeiro. Bivolt atende tanto 127V quanto 220V. |
| Elétrica | Soquete / Soquete de lâmpada | Bocal (Bocal Rabicho, Porcelana, Plafonier) |
Normaliza 'soquete' para 'bocal'. Não confunde bocal comum com plafonier de teto. |
| Elétrica | Fio Cabinho / Fio flexível | Cabo Flexível (1.5mm, 2.5mm, 4mm, 6mm, 10mm) |
Cabo condutor unipolar flexível. O bot jamais confunde com fio paralelo duplo ou cabo PP reforçado. |
| Elétrica | Disjuntor C20, C32, C40 | Disjuntor Monopolar / Bipolar |
A letra 'C' seguida do número indica a corrente nominal em amperes. Monopolar (1 fase), Bipolar (2 fases / 220V). |
| Elétrica | Caixinha de luz / Caixinha amarela | Caixa 4x2 / Caixa 4x4 |
Caixa de embutir na parede para interruptores e tomadas. |
| Hidráulica | Cotovelo (de qualquer bitola) | Joelho (90° ou 45°) |
No catálogo todos os cotovelos estão cadastrados como Joelho (Krona / Tigre). A conversão é 100% automática. |
| Hidráulica | Cano de 1/2" / Joelho de 1/2 (meia polegada) | Tubo / Joelho 20mm (Soldável Marrom) |
Conversão universal: 1/2 polegada equivale exatamente a 20 milímetros em tubulações de água fria soldável. |
| Hidráulica | Cano de 3/4" / Joelho de 3/4 (três quartos) | Tubo / Joelho 25mm (Soldável Marrom) |
Conversão universal: 3/4 polegada equivale exatamente a 25 milímetros no PVC marrom. |
| Hidráulica | Cano de 1" / Cano de 1 polegada | Tubo 32mm (Soldável Marrom) |
Conversão: 1" nominal equivale a 32mm na bitola externa do tubo soldável. |
| Hidráulica | Cano de 1.1/2" / Uma polegada e meia | Tubo 50mm (Soldável Marrom) |
Conversão: 1.1/2" equivale a 50mm soldável. |
| Hidráulica | Fita Teflon | Fita Veda Rosca (18x10, 18x25, 18x50) |
Veda conexões roscáveis metálicas ou de PVC para impedir vazamentos. |
| Hidráulica | Registro de Chuveiro | Registro de Pressão |
Regula a intensidade e vazão da água durante o banho. O bot distingue claramente do Registro de Gaveta (geral). |
| Hidráulica | Sifão Gaita / Sanfonado | Sifão Universal Sanfonado |
Conecta cubas e pias às saídas de esgoto (38mm, 40mm, 48mm, 50mm). |
| Hidráulica | Rabicho de pia / bacia | Engate Flexível (PVC ou Inox) |
Ligação flexível de 30cm, 40cm, 50cm ou 60cm para alimentação de caixas acopladas e torneiras. |
| Hidráulica | Carrapeta | Vedante Para Torneira |
Arruela de borracha que estanca pingadeiras em torneiras de reparo convencional. |
| Ferramentas | Chave Estrela / Chave de Cruz / Cruzada | Chave Philips |
Chave de fenda em formato de cruz para parafusos padrão Phillips. |
| Ferramentas | Chave de Boca / Chave Fixa | Chave Combinada ("Chave Porca Combinar") |
Chave com boca fixa de um lado e estria fechada do outro (6mm a 22mm). |
| Ferramentas | Chave Grifo / Chave de Cano | Chave Grife |
Ferramenta ajustável para tubos pesados e conexões roscáveis de ferro e PVC. |
| Ferramentas | Chave Inglesa | Chave Ajustável |
Chave regulável por rosca sem-fim para porcas e parafusos de várias medidas. |
| Ferramentas | Segueta | Arco de Serra / Lâmina de Serra |
Corte manual de metais, canos de PVC e perfis de madeira. |
| Ferramentas | Broca de Parede / Vídea | Broca Concreto |
Ponta com pastilha de metal duro (vídea) para furar alvenaria, tijolo e concreto. O bot nunca confunde com broca de ferro (aço rápido) ou madeira. |
| Pintura | Galão de Tinta (3,6 Litros) | Tinta Acrílica 3,6L (Beta Cor, Gertalar) |
Rende em média de 15m² a 20m² acabados com 2 demãos. Ideal para quartos ou salas pequenas. |
| Pintura | Lata / Balde de Tinta (16L / 18L) | Balde 16L / 18L |
Rende de 80m² a 100m² acabados com 2 demãos. Ideal para pintura de fachadas ou casa inteira. |
| Pintura | Quarto de Tinta / Latinha | Lata 900ml |
Frações de esmalte sintético ou verniz para pequenas portas, grades e retoques. |
| Pintura | Massa Corrida vs Massa Acrílica | Massa Corrida (Int) / Massa Acrílica (Ext) |
Massa Corrida PVA é estritamente para áreas internas secas. Massa Acrílica é resistente à umidade e chuva (fachadas e banheiros). |
| Pintura | Pincel | Trincha (1/2", 1", 1.1/2", 2", 2.1/2", 3", 4") |
Pincéis chatos para pintura e aplicação de esmaltes, vernizes e impermeabilizantes. |
| Fixação | Arame Queimado | Arame Recozido |
Arame maleável para amarração de ferragens e vigas de concreto armado. O bot distingue do galvanizado (resistente a ferrugem). |
| Fixação | Enforca Gato / Abraça-gato / Fita Hellermann | Abraçadeira de Nylon |
Cintas plásticas de aperto para organização de chicotes elétricos e fixações rápidas. |
| Fixação | Parabolt / Chumbador | Chumbador Metálico |
Ancoragem de cargas pesadas em concreto por expansão mecânica. |
| Fixação | Parafuso Soberba | Parafuso Sextavado Bucha |
Parafuso robusto para buchas de fixação em alvenaria e estruturas de madeira. |
| Colas | Cola de Cano | Adesivo Plástico para PVC (Krona / Amanco) |
Adesivo químico que realiza a fusão a frio das conexões e tubos soldáveis de PVC. |
| Colas | Super Bonder / Cola Maluca | Cola Instantânea Tekbond |
Adesivo à base de cianoacrilato para colagem rápida de alta resistência. |
| Colas | Cola de Sapateiro | Cola de Contato |
Para fórmicas, borrachas, couro, madeira e materiais flexíveis com cura por contato. |
| Colas | PU40 / Cola PU | Selante e Adesivo PU40 |
Poliuretano híbrido para vedação elástica de calhas, trincas, rufos e cubas. |
4. Motor de Busca Inteligente & Tolerância Dimensional
Algoritmo de pontuação ponderada em ferragens_consultar_produto()O catálogo da loja pode conter mais de 500 produtos com nomenclaturas semelhantes. Para evitar que um cliente que busque uma "tomada 20A" receba como sugestão uma tomada de 10A, ou que alguém buscando "cano de 25mm" receba um de 50mm, o motor de busca aplica regras estritas de Pontuação Ponderada e Penalização Dimensional.
Bonificação de Medida Exata
Quando a consulta contém uma medida específica (ex: 20A, 25mm, 100mm, 3.6L) e o produto do catálogo possui EXATAMENTE essa medida, o item recebe 40 pontos de afinidade imediata.
Penalização por Conflito Técnico
Se o cliente pediu 20A e o produto analisado é 10A, o item é penalizado severamente com -50 pontos, caindo para o fim da lista ou sendo completamente descartado.
[ALERTA DE VARIAÇÃO NÃO ENCONTRADA]. A IA é instruída a informar expressamente ao cliente que o item específico não consta no site e sugerir os produtos mais próximos disponíveis.
5. Ferramentas da IA (Function Calling)
Declaração de schemas e contratos JSON das ferramentas disponíveisO modelo de linguagem não responde de forma passiva. Ele tem acesso a ferramentas de execução em tempo real que consultam o catálogo e interagem com a retaguarda da loja física:
consultar_produto(query: string)
Pesquisa produtos cadastrados no arquivo produtos.json por nome, categoria, medida ou problema relatado pelo cliente.
{
"name": "consultar_produto",
"description": "Busca produtos no catálogo da Ferragens Camboatá por nome, categoria ou problema/aplicação. Retorna nome, categoria, preço e URL da foto.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Termo de busca (ex: 'joelho 25mm', 'tomada 20a', 'tinta acrilica branca')"
}
},
"required": ["query"]
}
}
notificar_atendente(produto_solicitado: string)
Disparada quando o cliente solicita um produto, medida ou marca que REALMENTE não consta no catálogo online, ou quando solicita cotações especiais fora do escopo do bot.
{
"name": "notificar_atendente",
"description": "Notifica os atendentes humanos da loja quando o cliente precisa de um produto não cadastrado no site.",
"parameters": {
"type": "object",
"properties": {
"produto_solicitado": {
"type": "string",
"description": "Nome exato do item, medida ou material solicitado pelo cliente que não consta no catálogo."
}
},
"required": ["produto_solicitado"]
}
}
6. Alertas de Falta de Produto & Notificação da Equipe
Mecanismo anti-ruído e envio de WhatsApp para a equipe de estoque
Quando o bot constata que um produto não está no catálogo do site, ele dispara uma mensagem automática via WhatsApp para a equipe de retaguarda da loja (telefones cadastrados: 5521998200616 e 5521971091494). Isso permite que a loja venda itens que estão no depósito físico mas ainda não foram colocados no site!
⚠️ *PRODUTO NÃO ENCONTRADO NO SITE*
👤 *Cliente:* João Silva
📱 *WhatsApp:* https://wa.me/5521999998888 (5521999998888)
🔍 *Produto solicitado:* Redução de 35mm para 1/2 Tigre
💬 *Mensagem do cliente:* "Vocês tem redução de 35mm pra meia polegada?"
👉 _O cliente precisa desse(s) produto(s) e ele(s) não constam no site. Por favor, verifique a disponibilidade no estoque físico e responda o cliente._
Filtro de Falsos Alarmes
Se o produto existe no catálogo com preço válido, o bot JAMAIS notifica como "não encontrado". Ele só alerta quando o item realmente não existe ou a medida não bate.
Janela de 3 Minutos por Cliente
Existe uma trava temporária em /tmp/ferragens_notif_{phone}.txt que impede envios múltiplos em cascata se o cliente repetir a mesma pergunta em menos de 180 segundos.
7. Takeover Humano & Comportamento em Grupos
Transição perfeita entre inteligência artificial e atendimento presencialUm dos maiores desafios de bots de WhatsApp é a disputa com atendentes humanos. O bot da Camboatá implementa um protocolo rigoroso para garantir que o humano tenha prioridade absoluta:
Pausa Automática de 120 Minutos
Sempre que um atendente da loja digita qualquer resposta para o cliente através do WhatsApp Web ou celular, o bot detecta a mensagem com is_human=1 ou prefixo de operador e entra em modo silencioso para aquele cliente durante 2 horas. Nenhuma resposta da IA será enviada até que expire a janela ou seja removida.
Apenas quando Mencionado
Em grupos de WhatsApp (identificados por @g.us, como o grupo oficial de consulta de preços), o bot só responde se for expressamente marcado (@) ou se a sua mensagem anterior for respondida/citada. O bot nunca se intromete nas conversas internas dos membros.
8. Regras Comerciais, Horários, Entregas & Envio de Fotos
Políticas físicas e operacionais da loja repassadas fielmente pelo bot| Item Operacional | Regra Oficial da Ferragens Camboatá | Comportamento do Bot |
|---|---|---|
| Localização Física | Estrada do Camboatá, 4253 — Costa Barros, Rio de Janeiro - RJ (CEP: 21650-100). | Informa o endereço exato, indica que o cliente pode retirar no balcão e disponibiliza orientações de chegada. |
| Horários de Funcionamento |
• Segunda a Sexta: 07:30 às 18:00 • Sábado: 08:00 às 17:00 • Domingos e Feriados: 08:00 às 12:00 |
Verifica dinamicamente o dia da semana e o horário de Brasília. Se o cliente perguntar "está aberto hoje?", responde com base no dia e hora exatos da consulta. |
| Formas de Pagamento |
• Loja Física: Dinheiro, PIX, Cartão de Débito e Crédito. • Site: PIX e Cartão de Crédito. |
Esclarece todas as formas aceitas de acordo com a preferência de retirada ou entrega do cliente. |
| Entregas / Frete | Entregas locais nos bairros de Guadalupe e Costa Barros (saídas a partir das 15h). Outros bairros: retirada no balcão ou sob consulta. | Confirma o bairro com o cliente antes de garantir a entrega imediata. Para bairros vizinhos, orienta falar com atendente para verificar rota. |
| Envio de Fotos de Produtos | Apenas fotos reais hospedadas no WordPress do site oficial da loja. | Insere a tag [ENVIAR_FOTO: url] ao final da mensagem. O webhook extrai a URL e dispara a imagem com a legenda do produto para o cliente. NUNCA inventa fotos! |
9. Manual Prático para Atendentes e Vendedores de Balcão
Dúvidas comuns e boas práticas para a equipe da loja físicaRecebi uma notificação no WhatsApp de produto não encontrado. O que fazer?
Abra o link do WhatsApp do cliente que veio na mensagem, verifique se temos o material na loja física ou depósito e passe o valor diretamente ao cliente. Quando você mandar a primeira mensagem, o bot entrará em pausa automática de 120 minutos para aquele cliente!
Preciso desativar o bot para responder um cliente?
Não! O sistema possui detecção de humano automática. Assim que você digitar uma mensagem da loja pelo WhatsApp Web ou aparelho físico, o bot automaticamente se afasta por 2 horas.
O preço de um produto mudou. Como atualizar o bot?
Basta atualizar o produto no Painel de Produtos do site. Como o bot lê diretamente o arquivo JSON do catálogo, o novo preço passa a valer instantaneamente para todas as próximas conversas!
O que acontece se o cliente mandar áudio ou foto?
Em mensagens de texto e respostas a Status/Stories do WhatsApp, o bot atende imediatamente. Caso o cliente mande um áudio ou imagem pura sem legenda descritiva, a equipe humana de plantão pode intervir para ouvir ou visualizar a peça solicitada.
10. Histórico de Versões & Manutenção
Changelog contínuo e registros de melhorias no motor de IA| Versão | Data | Principais Melhorias Implementadas | Status |
|---|---|---|---|
| v3.3.4 | Set/2026 |
• Implementação do Dicionário Mestre de 15 Categorias. • Resolução definitiva de 10A vs 20A / 10 Amperes vs 20 Amperes. • Conversão bidirecional de polegadas (1/2", 3/4", 1", 1.1/2") para milímetros. • Normalização de gírias (cotovelo → joelho, chave estrela → philips, soquete → bocal). • Sincronização unificada entre main-v2.js (site) e ferragens_bot.php (IA).
|
Produção |
| v3.3.0 | Ago/2026 |
• Filtro anti-falso-alarme em notificar_atendente (produtos existentes não disparam alerta).• Cooldown de 3 minutos por cliente para evitar spam de alertas. • Suporte robusto a respostas de Status do WhatsApp. |
Concluído |
| v3.0.0 | Jul/2026 |
• Integração com DeepSeek V3 via Function Calling. • Janela de 120 minutos de Takeover Humano persistente. • Envio automático de fotos reais de produtos via tag [ENVIAR_FOTO].
|
Concluído |