Chat

O Chat é o widget de conversa do SDK Zarv. Sua configuração é declarativa: você define window.ZarvConfig antes de carregar o loader e o widget auto-inicia, exibindo um launcher no canto da página.

🎮 Abrir o playground interativo → — teste os métodos, eventos e a configuração ao vivo, com a versão atual do SDK.

Configuração básica

<script>
  window.ZarvConfig = {
    publicKey: 'pk-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
    locale: 'pt',
    alignment: 'right',
  };
</script>
<script async src="https://js.zarv.com/sdk.js"></script>

O campo publicKey é obrigatório: é a chave pública do bot (pk-…), obtida no admin Zarv.

Opções de ZarvConfig

Campo	Tipo	Descrição
publicKey	string	Obrigatório. Chave pública do bot (pk-…) do admin Zarv.
backend	string	Host do backend de chat (REST). Por padrão, derivado do loader.
wsBackend	string	Host do WebSocket do chat, separado do backend (REST). Por padrão usa o host oficial; defina apenas para um backend self-hosted/local.
locale	'pt' | 'en'	Idioma da interface. Na ausência, cai no locale configurado no bot.
alignment	'right' | 'left'	Canto onde o launcher aparece. Default: 'right'.
horizontalPadding	number	Offset horizontal, em px, em relação à borda.
verticalPadding	number	Offset vertical, em px, em relação à borda.
actionColor	string	Cor (hex) do launcher e do botão de enviar.
theme	'auto' | 'light' | 'dark'	Tema da interface.
launcher.icon	string	Ícone exibido no launcher.
launcher.label	string	Rótulo exibido no launcher.
container	string | HTMLElement	Renderiza o chat inline dentro do elemento informado (sem launcher flutuante).
debug	boolean	Habilita afordances de diagnóstico. Nunca use em produção.

Métodos em runtime

Depois de carregado, o widget é controlado por chamadas à função global Zarv:

Chamada	Efeito
Zarv('show')	Abre o widget de chat.
Zarv('hide')	Fecha o widget de chat.
Zarv('shutdown')	Encerra a sessão atual e remove o widget.
Zarv('start')	Inicia (ou reinicia) o widget.
Zarv('setLocale', 'pt' | 'en')	Troca o idioma da interface em runtime.
Zarv('setTheme', 'auto' | 'light' | 'dark')	Troca o tema em runtime.
Zarv('identify', { userId, traits })	Identifica o usuário atual e anexa atributos (traits).

Nota: chamadas feitas antes do bundle terminar de carregar são enfileiradas e reproduzidas assim que o widget estiver pronto. Você não precisa esperar por nenhum evento de "ready".

Eventos

Inscreva-se em eventos do widget com Zarv('on', evento, handler) e cancele com Zarv('off', evento, handler). Você pode se inscrever a qualquer momento (antes ou depois do carregamento).

Zarv('on', 'message', ({ role, text }) => {
  console.log(role, text); // 'user' | 'assistant' | 'system'
});

Zarv('on', 'conversationStart', () => {
  // primeira mensagem do usuário — bom ponto para disparar analytics
});

Evento	Quando dispara	Payload
ready	o widget terminou de inicializar	—
open	o painel do chat foi aberto	—
close	o painel do chat foi fechado	—
message	uma mensagem entra na conversa (do usuário ou do bot)	{ role: 'user' | 'assistant' | 'system', text }
unread	o contador de não-lidas muda	count (número)
identify	Zarv('identify', …) é chamado	{ userId, traits }
conversationStart	a primeira mensagem do usuário na sessão	—

Os handlers são isolados: se um deles lançar erro, os demais continuam recebendo o evento. As inscrições persistem entre shutdown/start; o conversationStart volta a poder disparar após um shutdown.