AIVAX

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

Gerenciando sessões do cliente de chat

Uma sessão é uma única conversa entre um cliente de chat e um usuário final. Ela armazena o histórico de mensagens, o contexto da conversa, metadados, uma chave de acesso e uma tag opcional que identifica o usuário ou a conversa. As sessões expiram após um tempo configurado.

O cliente web e seu aplicativo criam sessões explicitamente por meio da API. Integrações as criam automaticamente, uma por conversa no aplicativo de mensagens.

Criar uma sessão #

Crie uma sessão a partir do seu servidor, com uma chave de API privada, quando um usuário iniciar uma conversa. Você pode fornecer contexto para toda a conversa, como o nome ou a localização do usuário.

A resposta contém:

  • sessionId: o identificador da sessão, usado para gerenciá-la com sua chave de API.
  • accessKey: a chave que autoriza Enviar Prompt e as outras rotas públicas da sessão.
  • talkUrl: o link para o chat web hospedado para esta sessão.

Qualquer pessoa com a chave de acesso ou o link pode usar a sessão. Forneça-os apenas ao usuário que possui a conversa e mantenha-os fora dos logs.

expires define a duração da sessão em segundos, contados a partir da criação ou atualização. Aceita valores de 600 segundos (10 minutos) até 7.776.000 segundos (90 dias) e o padrão é 3.600 segundos (uma hora).

Identificar usuários com uma tag #

Sem uma tag, cada sessão é uma conversa independente, acessível apenas por meio de sua chave de acesso.

Com uma tag, o AIVAX reutiliza a sessão ativa para essa tag em vez de criar uma nova. Criar uma sessão novamente com a mesma tag retorna a mesma sessão e mantém seu histórico de mensagens, mas substitui seu contexto, expiração e metadados pelos novos valores. Isso permite que um usuário retorne ao widget ou envie outra mensagem pelo mesmo canal sem perder a conversa.

A tag também conecta a sessão a outros recursos:

  • Memória precisa de um identificador estável para saber a quem pertence uma preferência salva.
  • Workers do Gateway e funções de protocolo recebem esse valor como externalUserId, para aplicar regras por usuário, canal ou conta externa.
  • Integrações usam o ID do chat ou número de telefone como a tag, para encontrar a sessão correta para cada conversa.

Escolha uma tag que seja estável, exclusiva por usuário ou conversa e não sensível, como um ID de usuário interno em vez de um endereço de e-mail.

Token de conversa #

Cada sessão possui um token de conversa que agrupa suas trocas em uma única conversa armazenada. O AIVAX cria e gerencia esse token; você nunca o envia, diferentemente do conversation_token em reutilização de sessão.

O token é renovado quando a conversa é limpa, por meio do reset do chat web ou pelo comando /reset nas integrações. As mensagens seguintes são então registradas como uma nova conversa, embora a sessão e sua tag permaneçam as mesmas.

Você pode ler o token no transcript da sessão, e as funções de protocolo e ferramentas MCP o recebem no contexto da chamada. Use-o para correlacionar chamadas da mesma conversa, não como prova de identidade ou permissão.

Escolher onde colocar o contexto #

O AIVAX aceita contexto em três lugares. Todos eles são adicionados às instruções do sistema da inferência, nesta ordem:

CampoQuando se aplicaUse para
extraContext (sessão)Toda inferência na sessão.Contexto para toda a conversa: o canal, o nome do usuário, plano, idioma preferido ou o produto sobre o qual a conversa versa.
contextLocation (sessão)O AIVAX busca a URL antes de cada inferência e anexa seu conteúdo após o extraContext.Contexto controlado pelo servidor que pode mudar durante a conversa, como o carrinho, o status de um pedido ou o registro aberto no seu aplicativo.
instructions (Enviar Prompt)Apenas nessa solicitação, anexado após o conteúdo do contextLocation.Contexto para aquele momento, como um formato de resposta temporário ou o item que o usuário acabou de selecionar.

Nenhum deles é salvo no histórico da sessão: o modelo vê a versão mais recente em cada solicitação. Como fazem parte das instruções do sistema, que iniciam cada solicitação, alterá-las invalida o cache de prompts para todo o histórico.

Mantenha o extraContext estável durante a conversa. Cada alteração nele, ou no conteúdo retornado por contextLocation, invalida o cache de prompts para todo o histórico, o que aumenta a latência e o custo de entrada na próxima solicitação. Para informações que mudam a cada solicitação ou que não são texto, use o campo context do Enviar Prompt: ele vai para a última mensagem do usuário em vez das instruções do sistema, assim o histórico em cache antes dessa mensagem é mantido. Veja Adicionar contexto descartável à última mensagem do usuário.

A mesma regra se aplica às integrações de canais: Telegram e WhatsApp colocam seu contexto fixo do canal, como regras de formatação e o nome de exibição do usuário, no extraContext da sessão.

Não coloque segredos, tokens internos ou dados que o modelo não deve ver em nenhum desses campos. Eles são enviados ao modelo e podem influenciar respostas, ferramentas e workers. Certifique-se de que a URL do contextLocation seja acessível pelo AIVAX; quando não puder ser carregada, a inferência continua sem ela e um aviso é adicionado aos logs da conta.

Listar e encerrar sessões #

Para revisar as sessões de um cliente de chat, com suas tags, carimbos de data/hora e contagens de mensagens e tokens, use Listar Sessões de Chat Web na referência da API.

Para encerrar uma sessão antes que ela expire, use Excluir Sessão de Chat Web. Sua chave de acesso e link param de funcionar imediatamente.

Digite para pesquisar na documentação.