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.

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. Aceita também tags regionais ('pt-BR', 'en-US'). Na ausência, ou com um idioma sem suporte, 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)). Não faz nada se esse publicKey já estiver iniciado.
Zarv('show')	Abre o widget de chat.
Zarv('hide')	Fecha o widget de chat.
Zarv('shutdown')	Encerra a sessão e remove o widget (todos os chats, se não indicar um).
Zarv('start')	Inicia (ou reinicia) o widget (todos os chats já iniciados, se não indicar um).
Zarv('setLocale', 'pt' | 'en')	Troca o idioma da interface em runtime. Aceita tags regionais ('pt-BR'); um idioma sem suporte é ignorado.
Zarv('setTheme', 'auto' | 'light' | 'dark')	Troca o tema em runtime.
Zarv('identify', { userId, traits })	Identifica o usuário atual e anexa atributos (traits). Antes de o chat ser aberto pela primeira vez, a identificação fica guardada e é enviada quando o visitante abre o chat.
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".

Desempenho da página: no carregamento, o widget faz uma única chamada à API (a configuração do bot). A sessão do visitante e o histórico da conversa só são buscados quando ele interage com o chat: ao passar o mouse, focar ou tocar no botão, ao abrir o painel ou ao enviar uma mensagem. Se o painel já estava aberto antes de um recarregamento, ou se o chat é inline, a sessão começa de imediato.

Com mais de um chat na página, cada método aceita { publicKey } como último argumento para escolher o chat. Veja Vários chats na mesma página.

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
});

Todo handler recebe um segundo argumento, { publicKey }, com o chat que emitiu o evento. Isso é útil quando a página tem vários chats:

Zarv("on", "message", ({ role, text }, { publicKey }) => {
  console.log(publicKey, role, text);
});

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	a identificação é enviada (na primeira abertura do chat, se identify veio antes)	{ 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.

Vários chats na mesma página

Chame Zarv('chat', …) uma vez por agente. Cada publicKey é um chat independente, com sua própria conversa. Chamar de novo com um publicKey já iniciado não faz nada.

Zarv("chat", { publicKey: "pk-vendas", alignment: "right" });
Zarv("chat", { publicKey: "pk-suporte", alignment: "left" });

Zarv("show", { publicKey: "pk-suporte" }); // abre só o de suporte
Zarv("sendMessage", "Oi", { publicKey: "pk-vendas" }); // envia só para vendas

Para escolher o chat, passe { publicKey } como último argumento de qualquer método da tabela acima. Sem ele:

• identify, setLocale e setTheme valem para todos os chats, inclusive os iniciados depois.
• shutdown encerra todos os chats e descarta essas configurações.
• show, hide e sendMessage valem para o primeiro chat iniciado. Numa página com um chat só, nada muda.
• start reinicia todos os chats que já foram iniciados.

Os launchers não se reposicionam sozinhos. Coloque cada chat flutuante num lado (alignment) ou afaste-os com horizontalPadding, senão um fica em cima do outro. Só um painel flutuante fica aberto por vez: abrir um fecha o outro. Chats inline (container) não seguem essa regra.

Se window.ZarvConfig declara um publicKey diferente, o Zarv('chat', …) não herda as opções dele.