---
url: https://developers.zarv.com/sdk/chat.md
description: >-
  Adicione o widget de conversa da Zarv com Zarv('chat', config): configuração,
  comandos em runtime, eventos e múltiplos agentes.
---

# Chat

O Chat é o widget de conversa do SDK Zarv. Sua configuração é **imperativa**, com a mesma estrutura do [Smartflow](/sdk/smartflow): você chama `Zarv('chat', config)` e o widget inicia, exibindo um launcher no canto da página.

## Configuração básica

```html
<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".

::: details 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`.

```html
<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](#varios-chats-na-mesma-pagina).

## 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).

```js
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](#varios-chats-na-mesma-pagina):

```js
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.

```js
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.