WhatsApp: assistente de IA
Como ajustar a voz do assistente, ensinar respostas fixas, auditar o que ele fez e testá-lo sem falar com clientes.
O assistente de IA atende o cliente no WhatsApp (e no chat da mini-loja): busca produtos, monta o carrinho, calcula frete, acompanha pedidos e passa para uma pessoa quando necessário. A loja não programa o assistente; ela ajusta como ele fala e o que ele sabe. Esta seção cobre os quatro pontos de ajuste da API: a persona (tom e instruções), a base de conhecimento (perguntas e respostas fixas), o registro de chamadas (para auditar e medir custo) e o playground (testar uma mensagem sem enviar nada ao cliente).
Como funciona
A cada mensagem do cliente, o assistente monta suas instruções a partir de três camadas, nesta ordem: o estilo base da persona, os ajustes de traços, e as suas instruções e o contexto da loja em texto livre. Em cima disso ficam as regras fixas da plataforma (não inventar dados, usar português correto, formato curto de resposta). As entradas ativas da base de conhecimento são oferecidas ao assistente como fonte. Cada chamada ao modelo gera uma linha no registro.
Estilos da persona
| Código | Tom |
|---|---|
P | Profissional, cortês e confiável (padrão). |
D | Natural e prestativo. |
A | Amigável, caloroso e próximo. |
R | Direto e objetivo. |
V | Leve e divertido, sem perder o profissionalismo. |
E | Eficiente, focado em resolver o pedido rápido. |
Traços
traits é um mapa de traço para more, default ou less. Os traços reconhecidos são acolhedor, entusiasmado, emoji, listas e tamanho. Um traço desconhecido é gravado e ignorado. O traço formato aceita enxuto (padrão), conversa ou resumo e muda o desenho das respostas (carrinho, opções).
Conceitos importantes
Instruções e contexto
custom_instructions são regras da loja ("nunca prometa entrega no mesmo dia"). store_context é o que o assistente deve saber da loja ("atendemos de segunda a sexta"). Ambos são texto livre.
Base de conhecimento
Serve para respostas que a plataforma não consegue calcular: política de troca, horário do ponto físico, certificações. Entradas desligadas (enabled false) não são usadas, e o recurso enable_kb precisa estar ligado (vem ligado). Se a loja tem poucas entradas ativas, todas vão para o assistente; com muitas, ele recebe as 3 que combinam por trecho (sem diferenciar maiúsculas) com a mensagem do cliente, na pergunta ou na resposta. O assistente também lê a base cadastrada na tela do seller.
Registro de chamadas
Cada chamada ao modelo grava tokens, tempo, resposta resumida e erro. O telefone do cliente é mascarado (só os quatro últimos dígitos aparecem). Serve para auditar o que o assistente respondeu e acompanhar custo.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /ai/persona | Lê a persona | admin |
| PUT | /ai/persona | Grava a persona | admin + manage_settings |
| GET | /ai/kb | Lista a base de conhecimento | admin |
| POST | /ai/kb | Cria uma entrada | admin + manage_settings |
| PUT | /ai/kb/{id} | Altera uma entrada | admin + manage_settings |
| DELETE | /ai/kb/{id} | Apaga uma entrada | admin + manage_settings |
| GET | /ai/logs | Lista o registro de chamadas | admin |
| POST | /ai/playground | Testa uma mensagem | admin + manage_settings |
Todos os caminhos acima começam com /api/v1/admin/whatsapp-confluence.
Erros comuns
- Mandar só o campo que quer mudar em
PUT /ai/persona: a persona é gravada inteira; campos omitidos voltam ao vazio (e o estilo volta aP). - Esquecer
enabledemPUT /ai/kb/{id}: o valor omitido conta comofalsee a entrada é desligada. - Apagar ou alterar uma entrada com id inexistente ou não numérico: a resposta é 200 e nada acontece.
- Esperar que o playground guarde histórico: cada chamada é independente.
- Procurar o telefone completo no registro: ele vem mascarado.
- Tratar
tool_callsdo registro como contrato estável: os nomes são internos e mudam.