O SDK do Chatwoot para sites permite que você envie informações adicionais do usuário para o Chatwoot.

Se você instalou nosso código no seu site, o SDK expõe o objeto `window.$chatwoot`. Para garantir que o SDK tenha sido carregado completamente, certifique-se de escutar o evento `chatwoot:ready` da seguinte forma:

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

Se você deseja escutar as mensagens no widget, pode usar o seguinte evento.

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

### Configurações do SDK[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#sdk-settings "Direct link to heading")

Para ocultar o balão, você pode usar a configuração mencionada abaixo.

**Observação**: Se você usar isto, também deve acionar o widget.

```
window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Desabilita o diálogo de mensagens não lidas
  position: "left", // Pode ser left ou right
  locale: "en", // Idioma a ser definido
  useBrowserLanguage: false, // Definir o idioma do widget pelo navegador do usuário
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // configure se quiser rastrear usuários entre subdomínios
};
```

### Usar idioma do navegador no widget de chat ao vivo automaticamente

Para exibir o widget de chat ao vivo no idioma do navegador do usuário, defina `useBrowserLanguage` como `true` em `window.chatwootSettings` mencionado acima.

**Observação**: Se `useBrowserLanguage` for definido como `true`, o `locale` mencionado será ignorado. Se o idioma do navegador não for suportado pelo Chatwoot, será usado o locale informado em `locale`. Caso também não haja essa configuração, o widget usará o `locale` do painel do agente.

### Modo Escuro[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#dark-mode "Direct link to heading")

O widget de chat ao vivo do Chatwoot suporta modo escuro a partir da versão v2.4.0. Para ativar o modo escuro, siga os passos mencionados [aqui](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/live-chat-dark-mode).

### Designs do widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-designs "Direct link to heading")

O Chatwoot suporta dois designs para o widget.

1. Padrão (default)

   ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeEpVVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cd7e6b995894f8afbcc4a48f8e159ae4e3a1a04b/standard-bubble-chatwoot-live-chatwoot.gif)

2. Balão expandido

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeE5VVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2b40967d868bb213b2d4e541ca3ed0e82c7222d0/expanded-bubble-chatwoot-live-chatwoot.gif)

Se você estiver usando o balão expandido, pode personalizar o texto utilizado no balão definindo o parâmetro `launcherTitle` nas chatwootSettings conforme mostrado abaixo.

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

### Habilitar janela popout[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

Para habilitar a janela popout, adicione a seguinte configuração em `chatwootSettings`. Esta opção fica desabilitada por padrão.

```
window.chatwootSettings = {
  // ...Outras configurações
  showPopoutButton: true,
}

Você também pode abrir a janela de chat como popout programaticamente com o método `popoutChatWindow()`.
```

### Mensagens personalizadas[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

Personalize as mensagens de boas-vindas e disponibilidade exibidas no cabeçalho do widget e indicadores de status da equipe.

```
window.chatwootSettings = {
  // ...Outras configurações

  welcomeTitle: "Precisa de ajuda?", // Cabeçalho personalizado do widget
  welcomeDescription: "Estamos aqui para te ajudar.", // Subtítulo do cabeçalho
  availableMessage: "Estamos online e prontos para conversar!", // Quando a equipe está online
  unavailableMessage: "No momento estamos offline." // Quando a equipe está indisponível
};
```

### Botões de ativação de recursos

Ative ou desative funcionalidades opcionais da interface dentro do widget:

```
window.chatwootSettings = {
  // ...Outras configurações

  enableFileUpload: true, // Exibir botão de anexar arquivo
  enableEmojiPicker: true, // Ativar seleção de emoji na entrada do chat
  enableEndConversation: true // Permite que usuários encerrem a conversa
};
```

### Abrir a janela popout programaticamente[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#programatically-open-the-popout-window "Direct link to heading")

Você pode abrir a janela popout programaticamente com o método `popoutChatWindow()`.

Para iniciar este processo, chame o método conforme abaixo.

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

### Alternar a visibilidade do balão do widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#toggle-the-widget-bubble-visibility "Direct link to heading")

Se quiser ocultar/exibir o balão do widget Chatwoot, utilize `toggleBubbleVisibility('show/hide')`

Exemplo

```
window.$chatwoot.toggleBubbleVisibility("show"); // para exibir o balão
window.$chatwoot.toggleBubbleVisibility("hide"); // para ocultar o balão
```

### Acionar o widget programaticamente

Se quiser abrir a janela de chat ao clicar em um link no site, siga o método abaixo. Na sua ação, chame o SDK do Chatwoot conforme descrito abaixo.

```
window.$chatwoot.toggle();

// Alternar widget especificando estado
window.$chatwoot.toggle("open"); // Para abrir o widget
window.$chatwoot.toggle("close"); // Para fechar o widget
```

### Definir o usuário no widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-the-user-in-the-widget "Direct link to heading")

```
window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", {
  email: "<email-address-of-the-user@your-domain.com>",
  name: "<name-of-the-user>",
  avatar_url: "<avatar-url-of-the-user>",
  phone_number: "<phone-number-of-the-user>",
});
```

`setUser` aceita um identificador, que pode ser o `user_id` em sua base de dados ou qualquer parâmetro único que represente um usuário. Você pode passar email, nome, avatar_url, phone_number como parâmetros. O suporte para parâmetros adicionais está em desenvolvimento.

Garanta que você reinicie a sessão quando o usuário fizer logout do seu app.

### Validação de identidade usando HMAC[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#identity-validation-using-hmac "Direct link to heading")

Para evitar personificação e manter a conversa com seus clientes privada, recomendamos configurar a validação de identidade no Chatwoot. A validação de identidade é feita gerando um HMAC (código de autenticação de mensagem baseado em hash) baseado no atributo `identifier`, usando SHA256. Junto com o `identifier`, você pode passar também o `identifier_hash`, como demonstrado abaixo, para garantir que o usuário está correto.

```
window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
  name: "", // Nome do usuário
  avatar_url: "", // URL do avatar
  email: "", // Email do usuário
  identifier_hash: "", // Hash do identificador gerado com base no webwidget hmac_token
  phone_number: "", // Número de telefone do usuário
  description: "", // descrição sobre o usuário
  country_code: "", // Código de país com duas letras
  city: "", // Cidade do usuário
  company_name: "", // nome da empresa
  social_profiles: {
    twitter: "", // Nome do usuário no Twitter
    linkedin: "", // Nome do usuário no LinkedIn
    facebook: "", // Nome do usuário no Facebook
    github: "", // Nome do usuário no Github
  },
});
```

Para gerar o HMAC, leia sobre [validação de identidade](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). Observação: implementar autenticação HMAC permite a persistência do histórico de chat entre sessões.

### Definir atributos personalizados[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-custom-attributes "Direct link to heading")

Para definir informações extras sobre o cliente, você pode usar o campo de atributos personalizados do cliente. Saiba mais sobre atributos personalizados [aqui](https://app.chatwoot.com/hc/chatwoot-user-guide-cloud-version/en/features-explained/470).

Para definir um atributo personalizado, chame `setCustomAttributes` conforme abaixo

```
window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // Aqui a chave precisa já estar definida como atributo personalizado
  // O valor deve ser baseado no tipo (Atualmente suporta Number, Date, String e Number)
});
```

Você pode visualizar essas informações no painel lateral de uma conversa.

Para deletar um atributo personalizado, use `deleteCustomAttribute` conforme segue

```
window.$chatwoot.deleteCustomAttribute("attribute-key");
```

### Definir idioma manualmente[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-language-manually "Direct link to heading")

```
window.$chatwoot.setLocale("en");
```

Para definir o idioma manualmente, use a função `setLocale`.

### Definir labels na conversa[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-labels-on-the-conversation "Direct link to heading")

Note que as labels serão definidas somente se o usuário ainda não iniciou uma conversa. Neste caso, os itens a seguir não terão efeito:

```
window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");
```

### Atualizar a sessão (use ao deslogar o usuário do seu app)[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#refresh-the-session-use-this-while-you-logout-the-user-from-your-app "Direct link to heading")

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

### Erros do widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-errors "Direct link to heading")

Para identificar erros no widget, certifique-se de escutar o evento `chatwoot:event` conforme abaixo:

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

Observação: Este recurso está disponível a partir da versão v2.3.0.

### Personalizar o cabeçalho de boas-vindas e descrição

Você pode alterar:

* O título e a descrição de boas-vindas

* Mensagens exibidas quando sua equipe estiver online ou offline

* Ativar ou desativar recursos da interface, como envio de arquivos, seleção de emoji e botão de encerrar conversa

```
window.chatwootSettings = {
  welcomeTitle: 'Precisa de ajuda?',
  welcomeDescription: 'Estamos aqui para te ajudar.',
  availableMessage: 'Estamos online e prontos para conversar!',
  unavailableMessage: 'No momento estamos offline.',

  enableFileUpload: true,
  enableEmojiPicker: true,
  enableEndConversation: true
 };
```