WhatsApp: conhecimento do assistente

O assistente de WhatsApp responde clientes sozinho. Para responder bem, ele precisa de duas coisas que a loja controla: uma base de conhecimento (os textos que ele pode usar) e um dicionário de correções (para entender como o cliente escreve). Esta seção cobre as duas, mais o registro das chamadas que o assistente faz a provedores de IA.

Como funciona

Fluxo típico para ensinar algo novo ao assistente:

1. Cadastre o texto

   POST /kb com title e content_text. Use status: "draft" se ainda estiver revisando.

2. Confira a busca

   POST /kb/search com uma pergunta de cliente. O texto novo deve aparecer em hits.

3. Ative

   PATCH /kb/{id} com status: "active". Se criou como ativa, esta etapa não existe.

4. Ensine as grafias

   POST /brand-corrections para cada apelido ou erro comum, e teste com POST /brand-corrections/test.

Estados de uma entrada da base:

Conceitos-chave

Índice de busca por significado

Quando a loja tem IA configurada, cada entrada ganha um índice que permite achar o texto pelo sentido da pergunta, mesmo com palavras diferentes ("quanto tempo para trocar" acha "Política de troca"). Sem IA, a busca cai num simples trecho de texto. has_embedding mostra se a entrada tem índice, e POST /kb/regenerate-embeddings completa os que faltam.

Loja inteira ou um seller

Numa loja com vários sellers (lojistas), cada seller pode ter entradas e correções próprias. As sem vendor_id são da loja e servem a todos. Quando você filtra por seller na busca, as entradas da loja toda entram junto.

Correção de marca

É um par "grafia errada, nome certo" com um peso. A grafia é guardada em minúsculas. Se duas correções disputam a mesma grafia, vence o maior peso. A plataforma também aprende grafias sozinha (source = auto-learned).

Custos em centavos

O custo de cada chamada de IA, quando conhecido, vem em centavos de real inteiros.

Endpoints

Erros comuns

• Criar a entrada como rascunho e esperar que o assistente a use: só active entra na busca.
• Usar PUT para alterar uma entrada: a rota é PATCH.
• Mandar tags em PATCH para acrescentar uma etiqueta: o campo substitui a lista inteira.
• Esperar que limit=500 valha em /kb ou /ai-logs: o teto é 200 e acima disso o limite vira 50.
• Tentar renomear a grafia de uma correção: só canonical e weight mudam. Apague e crie de novo.
• Rodar regenerate numa loja sem IA: a resposta é 503.
• Passar um id que não é UUID: a plataforma responde 500 em vez de 400.

Próximos passos