AIVAX

Esta página foi traduzida automaticamente do inglês e pode estar desatualizada. Leia o original

Visão geral dos clientes de chat

Um cliente de chat publica uma AI Gateway para os usuários finais. Ele oferece um local para conversar com o assistente — seja um chat web hospedado, seu próprio aplicativo, Telegram ou WhatsApp — enquanto a gateway continua respondendo com seu modelo, instruções, ferramentas e conhecimento. Os clientes de chat suportam conversas por texto, raciocínio profundo (deep thinking), busca e envio de imagens. As funcionalidades de áudio dependem do canal e da configuração do cliente.

Como funciona um cliente de chat #

Um cliente de chat é uma camada de sessão sobre uma AI Gateway. Eles têm funções separadas:

  • A AI Gateway define o que o assistente faz: modelo, instruções, ferramentas, RAG e habilidades.
  • O cliente de chat define como os usuários finais acessam o assistente: como uma conversa é identificada, quanto tempo ela dura, quais limites se aplicam, qual é a aparência da interface e como as mensagens entram e saem em cada canal.

Devido a essa divisão, uma única gateway pode atender uma API interna, um widget web, Telegram e WhatsApp simultaneamente. Cada canal mantém suas próprias regras para identidade, anexos, formatação, comandos e entrega de mensagens.

Cada conversa é uma sessão. Uma sessão armazena o histórico de mensagens, o contexto da conversa e metadados, expirando após um tempo configurado.

Escolha um canal #

CanalUse-o quandoGuia
Cliente WebVocê deseja incorporar o assistente em um site, produto, centro de suporte ou painel, ou chamá-lo a partir do seu próprio aplicativo.Cliente Web
TelegramVocê precisa de um bot simples com usuários identificados por chat e comandos fáceis de testar.Integrações
WhatsAppO principal canal de suporte dos seus usuários já é o telefone, através da Z-API, Evolution API ou Kapso.Integrações

O canal não deve alterar o que a gateway sabe ou faz. Ainda assim, pode ser necessário ajustar tom, comprimento da resposta, formatação e os anexos aceitos.

Criar um cliente de chat #

Crie o cliente de chat, vincule-o a uma AI Gateway e configure seus limites, interface e integrações. Você pode fazer isso no painel ou por meio da API:

Para alterar um cliente existente, use Editar Cliente de Chat Web na referência da API. Envie apenas os campos que deseja atualizar; os campos omitidos mantêm seus valores atuais.

As opções que são durações, como messageDebounceInterval, maxScheduledIgnoredZone e a sessionDuration das integrações, são números de segundos.

Limites #

Dois limites se aplicam a todas as sessões do cliente de chat, em todos os canais:

LimitePadrãoO que acontece ao atingi-lo
messagesPerHour20Novas mensagens dessa sessão são rejeitadas até que a janela de uma hora permita novamente.
maxMessages500A sessão não pode receber mais mensagens, e o usuário deve iniciar uma nova conversa.

No cliente web, uma mensagem rejeitada retorna um erro. Nas integrações, o usuário recebe uma mensagem do sistema no chat explicando o limite.

Defina ambos deliberadamente. Valores muito permissivos aumentam o custo e a exposição a abusos; valores muito restritivos prejudicam a experiência do usuário.

Antes de ir para o público #

  • Revise a configuração da gateway e do cliente de chat, e teste o canal com uma mensagem simples primeiro.
  • Mantenha as chaves de API no seu servidor. Os usuários finais recebem apenas a chave de acesso à sessão ou o link, nunca suas credenciais de conta. Consulte Autenticação para entender a distinção entre acesso ao chat público e credenciais de API.
  • Se a gateway usar memória persistente, explique aos usuários o que ela armazena. A memória é separada do histórico da sessão: ela sobrevive à sessão e está vinculada à tag da sessão. Consulte o guia de envenenamento de memória para revisar o contexto armazenado e testar sua influência em várias conversas.
  • Quando um canal não responde conforme o esperado, verifique a gateway vinculada e a configuração da integração, depois tente novamente com uma mensagem simples antes de investigar recursos opcionais.

Próximos passos #

  • Gerenciando sessões: crie sessões, identifique usuários e escolha onde colocar o contexto.
  • Cliente Web: personalize e incorpore o chat hospedado, ou envie prompts a partir do seu aplicativo.
  • Integrações: conecte Telegram e WhatsApp.

Digite para pesquisar na documentação.