Chat

O Chat é o widget de conversa do SDK Zarv. Sua configuração é imperativa, com a mesma estrutura do Smartflow: você chama Zarv('chat', config) e o widget 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 async src="https://js.zarv.com/sdk.js"></script>
<script>
  Zarv('chat', {
    publicKey: 'pk-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
    locale: 'pt',
    alignment: 'right',
  });
</script>

O campo publicKey é obrigatório: é a chave pública do bot (pk-…), obtida no admin Zarv. Chamadas feitas antes do bundle carregar são enfileiradas e reproduzidas — não é preciso esperar nenhum evento de "ready".

Alternativa declarativa (window.ZarvConfig)

A forma anterior continua suportada: defina window.ZarvConfig antes do loader e o widget auto-inicia. Um Zarv('chat', config) posterior mescla por cima do ZarvConfig.

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

Opções de configuração

O mesmo objeto de configuração vale para Zarv('chat', config) e para o window.ZarvConfig declarativo.

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('chat', config)	Inicia o widget com a configuração dada (mesma estrutura do Zarv('smartflow', config)). No-op se já iniciado.
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).
Zarv('sendMessage', text)	Abre o painel e envia text como mensagem do usuário (o bot responde). Ideal para botões "falar com suporte" que já iniciam a conversa com um contexto.

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.