--- id: casos/assistente-whatsapp area: IA uso: comum esforco: médio grao: Item ofertável x tenant para o agente; mensagem e conversa para o monitoramento --- # Assistente de IA no WhatsApp O cliente pergunta no WhatsApp por um imóvel, produto ou horário e recebe na hora uma resposta tirada de uma tabela pronta, só com o que está disponível, e passa para um humano quando a IA não deve responder. ## Resumo executivo **Para quem:** Empresas que atendem o cliente final no WhatsApp e querem que a IA responda com o catálogo e a disponibilidade reais. **O que resolve** - A IA só oferece o que está disponível hoje, com o preço certo, e não inventa item. - A mensagem escrita do jeito do cliente acha o item certo, mesmo com o cadastro abreviado. - Fica medido quanto a IA resolveu sozinha, quanto passou para um atendente e quantas visitas marcou. **Por que importa:** No WhatsApp a resposta vai direto para o cliente, sem ninguém revisar. Um imóvel vendido oferecido como disponível ou um preço velho custa a venda e a confiança. E como o canal é externo, uma credencial aberta demais ou uma consulta montada com o texto do cliente vira risco de vazamento. **Perguntas de negócio que responde** - Quantas conversas a IA resolveu sozinha nesta semana e quantas passaram para um atendente? - Quantas visitas ou agendamentos a IA marcou no mês, por loja ou unidade? - Quantas mensagens de clientes chegam fora do horário comercial? - Sobre quais itens a IA não soube responder? - Algum item vendido ou indisponível foi oferecido pela IA nos últimos dias? **O que você precisa** - O sistema que guarda o catálogo e a disponibilidade conectado na Nekt (CRM, ERP ou banco do site) - A ferramenta de WhatsApp com o histórico de mensagens chegando ao lakehouse (conector ou webhook) - A regra do negócio para o que pode ser oferecido e quando a conversa vai para um humano **O que você recebe** - Uma tabela de consumo por tenant, uma linha por item ofertável, com texto pronto para o agente - Um índice de busca que traduz o jeito do cliente escrever para o código do cadastro - Uma credencial do agente restrita às tabelas de consumo - Um painel de atendimento: resolvido pela IA, transbordo, fora do horário e agendamentos ## Detalhado ### O problema O agente de WhatsApp lê o catálogo bruto do CRM: oferece imóvel já vendido, mostra preço zerado, não acha o produto porque o cadastro está abreviado e mistura os itens de dois clientes que usam o mesmo agente. Depois ninguém sabe dizer quanto a IA resolveu, porque conversa de um turno conta como atendimento e status de pré-agendamento conta como visita. ### Regras de negócio 1. **Uma tabela de consumo só com o que pode ser oferecido.** O agente não lê o catálogo bruto. Monte uma tabela de consumo com os itens elegíveis pela regra do negócio: imóvel marcado para exibição no site e com status de venda, venda e aluguel ou em negociação; lançamento separado de usado; locação com aluguel maior que zero e abaixo de um teto que corta valor digitado errado; produto ativo. Uma linha por item, com as colunas que o cliente pergunta: tipo, bairro, quartos, área, valor e link. (Evite: Apontar o agente para a tabela inteira do CRM e confiar no prompt para filtrar.) 2. **Texto pronto e preço formatado na tabela.** Campos aninhados (infraestrutura, características, fotos) viram texto legível, com um rótulo por campo. Valor sai no padrão brasileiro (R$ 1.250.000,00). Valor zero ou nulo vira uma frase fixa, como 'Entre em contato para informações de valores', nunca R$ 0,00. Lançamento mostra 'a partir de'; usado mostra o valor. A primeira foto vem com URL pública. (Evite: Deixar a IA formatar preço e interpretar JSON aninhado.) 3. **Busca pelo jeito que o cliente escreve.** O motor SQL do lakehouse não tem função de similaridade de texto. Pré-compute um índice invertido com peso pela raridade do termo e um dicionário de apelidos validado pela área (qj para queijo, bov para bovino). Marque qual palavra do cadastro é a categoria: em muitos ERPs a primeira palavra da descrição é o produto e o resto é marca ou sabor. Sem isso, quem pede picanha recebe um empanado sabor picanha. (Evite: LIKE no nome do produto com o texto da mensagem.) 4. **O agente nunca monta SQL com o texto do cliente.** Canal externo é superfície de ataque. As consultas ficam fixas no backend; o texto do cliente entra só como parâmetro, validado por lista de caracteres permitidos. A credencial do agente é um token MCP com escopo nas tabelas de consumo, nunca uma chave de API com acesso total. O escopo é congelado na criação: incluir uma tabela exige gerar e trocar o token, e a data de vencimento do token entra no monitoramento. (Evite: Agente livre para gerar SQL com uma chave de administrador.) 5. **tenant_id em toda linha e caches separados.** Quando o mesmo agente atende vários clientes, cada linha leva o tenant_id e o agente filtra por ele sempre. O cache de itens e o cache de contatos ficam em tabelas separadas, cada uma com o seu tenant. Cliente novo entra por configuração, não copiando a transformação de outro. (Evite: Um cache só com os imóveis de todos os clientes, filtrado pelo prompt.) 6. **O que o cliente pode ver é decisão de governança.** Expor estoque, custo ou dado de outro cliente num canal externo exige aval escrito. Num caso real, foi aprovado responder se há estoque, não quanto há. Registre a condição junto da aprovação: se o agente passar a mostrar a quantidade, a aprovação deixa de valer. Dado pessoal de outros contatos nunca sai na resposta. (Evite: Responder a quantidade em estoque porque a coluna está na tabela.) 7. **Inexistente e indisponível são respostas diferentes.** Se o item não existe no catálogo, o agente diz que não encontrou e oferece parecidos. Se existe e está sem estoque, vendido ou reservado, diz que está indisponível. Item vendido ou reservado nunca aparece como disponível. (Evite: A mesma resposta 'não temos' para os dois casos.) 8. **Transbordo para humano tem gatilho e registro.** Escreva quando a IA passa a conversa para um atendente: negociação de preço, reclamação, envio de documento, pergunta fora do catálogo ou pedido do cliente. Cada transferência fica registrada com motivo, fila e horário. O indicador é a parcela de atendimentos resolvidos sem transbordo, por fila e por dia fechado. (Evite: IA tentando responder tudo, sem registro de quando desistiu.) 9. **Meça pelo que aconteceu, não pelo status.** Conversa real tem mais de um turno; conversa de um turno é só a abordagem inicial. Agendamento conta só quando existe na tabela de agendamentos; status como pré-agendado ou em atendimento não é visita. Se cliente e IA gravam o mesmo horário em cada turno, o tempo de resposta não é calculável e não deve ser reportado. (Evite: Contar conversas e status do atendimento como resultado da IA.) 10. **Frescor faz parte da resposta.** A tabela de consumo roda por evento logo depois da fonte, nunca em gatilho manual. Cada linha guarda a data da última carga. Se a carga atrasou além do limite combinado, o agente não confirma disponibilidade e diz que um atendente vai confirmar. (Evite: Atualizar o cache uma vez por semana ou à mão.) ### Como medir o atendimento da IA A partir do histórico de conversas, mensagens, transferências e agendamentos. - **Mais de um turno entre cliente e IA** → Conversa real - **Fechado sem transferência para humano** → Resolvido pela IA - **Transferência registrada com motivo** → Transbordo - **Mensagem do cliente fora do horário configurado** → Fora do horário - **Registro na tabela de agendamentos** → Agendamento real - **Status de entrega com erro** → Mensagem com falha - **Pré-agendado, em atendimento, conversa de um turno** → Não conta como resultado ### Definições | Métrica | Definição | |---|---| | Item elegível | item que passa na regra de exibição do negócio na última carga: ativo, liberado para divulgação e com status ofertável | | Conversa real | conversa entre cliente e agente com mais de um turno, no período | | Resolvido sem transbordo | atendimentos fechados no dia fechado, no fuso local, sem transferência para humano / atendimentos fechados no mesmo dia | | % fora do horário | mensagens do cliente fora do horário da loja / mensagens do cliente em lojas com horário configurado; loja sem horário fica fora da conta | | Agendamento | registros criados pela IA na tabela de agendamentos no período; status de pré-agendado não conta | | Acerto de busca | perguntas de teste em que o item certo aparece entre os N primeiros resultados / perguntas de teste | | Tempo até a resposta final | da mensagem do cliente até a última resposta final do agente, ignorando mensagens intermediárias de espera | ### Armadilhas - **Item fora do site oferecido.** O agente lia o cadastro inteiro do CRM e oferecia imóveis que não estavam liberados para divulgação ou já estavam vendidos. Como evitar: Aplique a regra de exibição na tabela de consumo, não no prompt. - **Produto errado com confiança.** A busca devolvia um empanado sabor picanha para quem pedia picanha, porque a descrição curta ganhava o ranking. Apertar o limiar para ter resposta única piorou. Como evitar: Marque o termo de categoria e meça o acerto entre os N primeiros. - **Status somado como visita.** Dezenas de status livres do atendimento foram agrupados e o pré-agendado entrou como visita marcada pela IA. Como evitar: Agendamento só existe na tabela de agendamentos. - **IA ligada que nunca conversou.** Num retrato, boa parte das lojas tinha a IA ligada e nenhuma conversa real. O indicador de IA ligada vinha verdadeiro por padrão mesmo sem o módulo contratado. Como evitar: Considere operante só quem tem o módulo contratado e a IA ligada, e meça conversa real. - **Mídia que expira.** Os links de áudio e imagem entregues pela ferramenta de WhatsApp expiram em cerca de 30 dias, e o histórico ficou sem o conteúdo. Como evitar: Baixe a mídia e transcreva os áudios de forma incremental logo depois de cada carga. - **Histórico que anda.** A API da ferramenta de atendimento só devolvia as últimas semanas de tickets. A tabela era uma janela que andava e o mês anterior tinha menos da metade dos tickets reais. Como evitar: Acumule numa tabela própria, um registro por id, com a versão mais recente vencendo. ### Teste de aceitação - [ ] Nenhum item da tabela de consumo está vendido, reservado, inativo ou fora da divulgação na fonte, na mesma data de carga. - [ ] Para cada tenant, a contagem de itens da tabela de consumo bate com a contagem de itens elegíveis no CRM daquele cliente. - [ ] Num conjunto de pelo menos 30 perguntas reais de clientes, o item certo aparece entre os 3 primeiros resultados em pelo menos 9 de cada 10. - [ ] Uma consulta com o token do agente a qualquer tabela fora das de consumo devolve erro de acesso. - [ ] Atendimentos resolvidos pela IA + atendimentos transferidos = total de atendimentos fechados no dia, sem sobra. ### Context document ```text Assistente de atendimento no WhatsApp - Responda só com dados das tabelas de consumo do agente: , . Nunca use o catálogo bruto. - Filtre sempre pelo tenant_id . Nunca mostre item ou contato de outro tenant. - Item disponível = item presente na tabela de consumo na última carga. Vendido, reservado ou inativo não é oferecido. - Se o item não existe, diga que não encontrou e ofereça até 3 parecidos. Se existe e está indisponível, diga que está indisponível. - Preço: use o campo formatado. Valor ausente: 'Entre em contato para informações de valores.' Lançamento: 'a partir de'. - Estoque: diga se há, não quanto há, salvo aprovação registrada. - Nunca informe dado pessoal de outros contatos, custo, margem ou comissão. - Passe para um atendente quando houver negociação de preço, reclamação, envio de documento, pergunta fora do catálogo ou pedido do cliente. Registre o motivo. - Se a última carga tiver mais de horas, não confirme disponibilidade: diga que um atendente vai confirmar. - Fora do horário da loja, informe o horário de atendimento e ofereça agendamento. Exceções por cliente: - : regra de exibição = igual a 'Sim' e status em . - : dicionário de apelidos aprovado em pela área <área>. - : estoque pode ser informado em quantidade (aprovação de ). ``` ### Variações - **Site e portais:** A mesma tabela alimenta o site e o feed XML dos portais imobiliários, com URL pública das fotos. - **Busca semântica:** Uma linha de texto por item enviada a um banco vetorial, com metadados para filtrar por tenant e status. - **Vendedor interno:** O mesmo índice atende o vendedor que pergunta no WhatsApp se há o produto no centro de distribuição, sem expor a quantidade.