![Visão geral do SDK do chat no site: aguardar o evento chatwoot:ready, identificar o usuário com setUser, enviar atributos personalizados, ajustar o widget em chatwootSettings e controlá-lo por métodos.](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbUVRIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--723e01782fb74aca2b43405056f5cf8f3e852863/1730215568-como-enviar-informacoes-adicionais-de-usuario-para-o-chatwoot-com-sdk.png)

O SDK do Chatwoot permite enviar informações adicionais dos seus usuários para o Chatwoot, tornando o atendimento pelo **chat no site** mais personalizado e eficiente. Este guia mostra como identificar quem está conversando (`setUser`) e enviar **atributos personalizados**, além das demais configurações do widget.

Ao instalar o código do Chatwoot no seu site, o SDK expõe o objeto `window.$chatwoot`. Para garantir que o SDK foi carregado por completo, escute o evento `chatwoot:ready` antes de chamar qualquer método:

```js
window.addEventListener("chatwoot:ready", function () {
  // Use window.$chatwoot aqui
  // ...
});
```

Para escutar as mensagens trocadas no widget, utilize o evento abaixo:

```js
window.addEventListener("chatwoot:on-message", function (e) {
  console.log("chatwoot:on-message", e.detail);
});
```

## Definir o usuário no widget (`setUser`)

Se você já conhece quem está navegando (por exemplo, um cliente logado no seu site), use `setUser` para identificá-lo no Chatwoot. O primeiro argumento é um **identificador único** do usuário; o segundo é um objeto com os dados dele:

```js
window.$chatwoot.setUser("<identificador-único-do-usuário>", {
  email: "maria@exemplo.com",
  name: "Maria Silva",
  avatar_url: "https://exemplo.com/maria.png",
  phone_number: "+5511999999999"
});
```

Chame `setUser` sempre depois do evento `chatwoot:ready`. Informe pelo menos um valor válido em `name`, `email` ou `avatar_url`; se enviar `phone_number`, use o formato internacional E.164, começando por `+` e o código do país.

### Validação de identidade com HMAC

Para evitar falsificação de identidade e garantir a privacidade das conversas, ative a validação de identidade gerando um `identifier_hash` a partir de um token HMAC. Com a validação ativa, você pode enviar o conjunto completo de campos de contato:

```js
window.$chatwoot.setUser("<identificador-único>", {
  name: "Maria Silva",
  avatar_url: "https://exemplo.com/maria.png",
  email: "maria@exemplo.com",
  identifier_hash: "<hash-HMAC-gerado-no-servidor>",
  phone_number: "+5511999999999",
  description: "Cliente desde 2024",
  country_code: "BR",
  city: "São Paulo",
  company_name: "Empresa Exemplo",
  social_profiles: {
    linkedin: "https://www.linkedin.com/in/maria-exemplo",
    facebook: "https://www.facebook.com/maria.exemplo",
    github: "https://github.com/maria-exemplo"
  }
});
```

Para gerar o token HMAC e habilitar esse recurso, veja [Como habilitar a validação de identidade no Chatwoot?](1730216029-como-habilitar-a-validacao-de-identidade-no-chatwoot).

## Definir atributos personalizados

Use `setCustomAttributes` para adicionar informações extras sobre o cliente (por exemplo, plano contratado ou ID interno):

```js
window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "pago"
});
```

Para remover um atributo, use `deleteCustomAttribute`:

```js
window.$chatwoot.deleteCustomAttribute("nome-do-atributo");
```

## Configurações do SDK

Defina as preferências do widget no objeto `window.chatwootSettings`. Para ocultar a bolha de mensagens, defina `hideMessageBubble` como `true` (nesse caso, lembre-se de acionar o widget manualmente):

```js
window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Desativa o diálogo de mensagens não lidas
  position: "left",                // Pode ser "left" ou "right"
  locale: "pt",                    // Idioma do widget
  useBrowserLanguage: false,       // Usa o idioma do navegador do usuário
  type: "standard",                // [standard, expanded_bubble]
  darkMode: "auto"                 // [light, auto, dark]
  // baseDomain: "seudominio.com"  // Rastrear usuários entre subdomínios
};
```

### Usar o idioma do navegador

Para exibir o widget no idioma do navegador do usuário, defina `useBrowserLanguage` como `true`. Observação: se `useBrowserLanguage` estiver como `true`, o valor de `locale` será ignorado. Se o idioma do navegador não for suportado pelo Chatwoot, o widget usará o idioma configurado em `locale`.

### Modo escuro

Defina `darkMode` como `auto` para acompanhar o tema do dispositivo, `dark` para manter o modo escuro ou `light` para manter o modo claro.

### Modelos de widget

O Chatwoot oferece dois modelos de widget: o padrão (`standard`) e a bolha expandida (`expanded_bubble`). Para personalizar o texto da bolha expandida, utilize o parâmetro `launcherTitle`:

```js
window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "Converse conosco"
};
```

### Ativar a janela pop-out

Para habilitar a janela pop-out, adicione a configuração abaixo ao `chatwootSettings`:

```js
window.chatwootSettings = {
  showPopoutButton: true
};
```

Você também pode abrir a janela pop-out programaticamente:

```js
window.$chatwoot.popoutChatWindow();
```

## Controlar o widget programaticamente

### Alternar a visibilidade da bolha

Para mostrar ou ocultar a bolha do Chatwoot, use `toggleBubbleVisibility`:

```js
window.$chatwoot.toggleBubbleVisibility("show"); // mostrar a bolha
window.$chatwoot.toggleBubbleVisibility("hide"); // ocultar a bolha
```

### Abrir o widget programaticamente

Para abrir o chat ao clicar em um link ou botão, use o método `toggle`:

```js
window.$chatwoot.toggle();        // Alterna o estado
window.$chatwoot.toggle("open");  // Abre o widget
window.$chatwoot.toggle("close"); // Fecha o widget
```

### Definir o idioma manualmente

Use `setLocale` para definir o idioma do widget:

```js
window.$chatwoot.setLocale("pt");
```

### Aplicar etiquetas na conversa

Para adicionar ou remover etiquetas de uma conversa, use `setLabel` e `removeLabel`:

```js
window.$chatwoot.setLabel("suporte");
window.$chatwoot.removeLabel("suporte");
```

### Reiniciar a sessão

Ao desconectar o usuário do seu site, reinicie a sessão do widget:

```js
window.$chatwoot.reset();
```

## Tratar erros do widget

Para detectar erros no widget, escute o evento `chatwoot:error`:

```js
window.addEventListener("chatwoot:error", function () {
  // ...
});
```

**Observação:** este recurso está disponível a partir da versão 2.3.0.