> For the complete documentation index, see [llms.txt](https://sejasuri.gitbook.io/webchat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sejasuri.gitbook.io/webchat/conceitos-e-metodos.md).

# Conceitos e métodos

O WebChat consiste em um canal onde a Suri pode te ajudar a atender e se relacionar com seus clientes no domínio da Web, em seu site ou mesmo aplicativo. Você consegue atender todas as pessoas que entram em contato através do WebChat no [Portal](https://portal.chatbotmaker.io/), na página de mensagens, juntamente com os demais canais conectados à Suri.

### Sessão

Cada vez que uma pessoa acessa seu site onde o WebChat está configurado, criamos uma sessão para ela. Nesta sessão, a pessoa é identificada como um contato e pode trocar mensagens através do WebChat com a Suri ou sua equipe de atendimento. Para manter a referência de tal contato em todas as páginas de seu site ou em caso de recarregamento de página, utilizamos `cookies`, onde salvamos uma identificação básica do contato (o ID) e o utilizamos para buscar todo o histórico de mensagens.

{% hint style="info" %}
Como utilizamos cookies para identificação do contato, é importante sinalizar aos visitantes do seu site o uso de tal artifício, visto que é uma etapa exigida pela Lei Geral de Proteção de Dados (LGPD). O cookie salvo não contém nenhuma informação sensível do contato, como nome ou e-mail, mas sim, apenas um identificador que é utilizado internamente em nossa aplicação e sua exposição não implica em nenhum risco à privacidade.
{% endhint %}

Como o registro da sessão depende de cookies, é importante notar que, caso a mesma pessoa acesse o site por um dispositivo diferente, navegador diferente, ou mesmo aba anônima de navegador, irá ser criado outro contato com outra sessão.

### Entidades

Atualmente possuímos estas entidades no WebChat, que representam conceitos básicos:

* `WebUser`: o contato, ou seja, o usuário que entrará em contato com a Suri através do WebChat. As propriedades de um contato são as seguintes:

```javascript
interface WebUser {
    id?: string; // opcional
    name?: string; // opcional
    email?: string; // opcional
    phone?: string; // opcional
    gender?: number; // opcional (0 para Masculino, 1 Feminino e 2 Neutro)
    imageUrl?: string; // opcional
    note?: string; // opcional
    tags?: string[]; // opcional
    identificationDocument?: string; // opcional
    ref?: string; // opcional
}
```

* `WebMessage`: uma mensagem recebida ou enviada pelo WebChat. As propriedades de uma mensagem são as seguintes:

```javascript
interface WebMessage {
    isChatbot: boolean; // indica se mensagem foi enviada pela Suri
    type: string;
    body?: string; // opcional (sempre preenchido quando mensagem é de texto)
    attachment?: string; // opcional (sempre preenchido quando mensagem é de anexo - imagem, áudio, etc.)
}
```

Veremos, através dos métodos, como utilizar tais entidades para maximizar o uso do WebChat.

### Métodos

Recomendamos uma noção básica de Javascript e programação para leitura desta seção.

Ao inserirmos o `script` do WebChat em um site, na prática estamos inserindo nosso SDK que dá acesso a objetos e métodos referentes ao canal de chat, onde podemos realizar alterações de dados em nossos contatos e receber eventos lançados pela Suri (webhooks).

O método `cbAsyncInit` é o responsável por delimitar o escopo onde podemos utilizar o SDK do WebChat, pois ele garante que o SDK está carregado e pronto para uso:

<pre class="language-javascript"><code class="lang-javascript"><strong>window.cbAsyncInit = function () {
</strong><strong>    CBM.ChatbotId = "cbXXXX"; // ID da Suri
</strong>};
</code></pre>

Dentro dele primeiramente determinamos a qual Suri está conectada ao WebChat em questão adicionando o ID (ver página [Configuração](/webchat/configuracao.md)) e logo em seguida chamamos o primeiro método: `StartWebChat`. Segue abaixo lista dos métodos disponíveis:

* [StartWebChat](#startwebchat)
* [UpdateUser](#updateuser)
* [OnReceiveMessage](#undefined)

#### StartWebChat

É o responsável por criar um novo contato. Ele é executado no momento que o chat é renderizado na página para o visitante do site e pode receber alguns parâmetros (todos opcionais), sendo eles: `user`, `showPopup` e `elementId`, respectivamente. Segue abaixo uma explicação dos três.

* `user`: dados desejados para o contato a ser criado. Utilizamos a interface `WebUser`, definida mais acima na sessão [Entidades](#entidades).
  * Interessante de ser usada para identificar visitantes do site que podem ser mapeados. Por exemplo, uma pessoa está acessando a área de membros do seu site que possui WebChat, onde você tem acesso ao nome e e-mail dela e quer que isso seja refletido no Portal de atendimento da Suri.
* `showPopup`: se você deseja que o WebChat seja visualizado por padrão em seu modo fechado (apenas botão flutuante) ou aberto (com o chat aparecendo). Padrão: `false`.
* `elementId`: ID de um elemento `HTML` no qual você deseja renderizar o WebChat. Padrão: `null`, que renderiza o WebChat no canto inferior direito do site.
  * Interessante quando você quer usar o WebChat como forma de comunicação mais controlada, por exemplo, dentro de uma parte de uma página (e não na página inteira)
  * Este parâmetro também é muito usado para quem possui um aplicativo e deseja utilizar o WebChat como canal de chat no app. Geralmente aconselhamos a criar uma `WebView` dentro do app e, dentro dela, criar um elemento `div`, apontando seu WebChat para o id de tal elemento.

```javascript
function getUserName () { ... }
function getUserEmail () { ... }

var user = {
    name: getUserName(),
    email: getUserEmail()
} as WebUser;

CBM.StartWebChat(user, showPopup: false, elementId: null).then(webChat => {
    console.log("webChat.User = ", JSON.stringify(webChat.User));
    // webChat.User = {
    //    id: "wcXXXX", // id criado pelo SDK, fica salvo no site em cookies
    //    name: "...",
    //    email: "..."
    // }
}).catch(reason => {
    // algum tratamento de erro
});
```

{% hint style="info" %}
O objeto retornado pela `Promise` do método `StartWebChat` será usado para os demais métodos descritos nesta página. Aconselhamos salvá-lo em uma variável de acesso maior para que possa ser utilizado em outras partes do código sem gerar problemas de gargalo, visto que o método `StartWebChat` é chamado a cada carregamento de página para verificar se o presente usuário já está criado no WebChat.
{% endhint %}

#### UpdateUser

Como o próprio nome diz, atualiza o usuário. Esta função recebe como parâmetro um objeto do tipo `WebUser` e realiza as atualizações necessárias no usuário em questão. Segue exemplo abaixo:

```javascript
let webChatClient = null;

CBM.StartWebChat(/* parâmetros iniciais */).then(webChat => {
    webChatClient = webChat;
}).catch(reason => {
    // algum tratamento de erro
});

// ...

// em algum momento desejado
if (webChatClient) {
    webChatClient.UpdateUser({
        name: '<novo nome>',
        imageUrl: '<url da nova foto>'
    })
    .then(res => { /* ... */ })
    .catch(err => { /* ... */ });
}
```

{% hint style="info" %}
Note que o método UpdateUser está encapsulado no objeto retornado pela `Promise` do método `StartWebChat`. Isso ocorre porque utilizamos a sessão já criada do contato para realizar ações na Suri, por medidas de segurança. Sempre sugerimos que salve o resultado de tal `Promise` em uma variável de acesso maior, permitindo seu uso fora do escopo do método, como no exemplo acima.
{% endhint %}

#### OnReceiveMessage

Funciona como *webhook* para receber evento de nova mensagem na conversa do contato em questão. Toda vez que uma mensagem for enviada ou recebida pelo WebChat na conversa com o contato, esse método irá ser chamado, podendo assim, ser realizada alguma ação customizada.

Por exemplo, suponha que a cada mensagem recebida no site, você queira disparar uma notificação para alertar o contato quando sua equipe de atendimento enviar uma mensagem para o contato:

```javascript
function sendLocalNotification(title, content) { /* ... */ }

CBM.StartWebChat(/* parâmetros iniciais */).then(webChat => {
    
    webChat.OnReceiveMessage(message => {
        sendLocalNotification('Nova mensagem', message.body);
    });

}).catch(reason => {
    // algum tratamento de erro
});
```

### Explorando mais possibilidades

Algumas outras personalizações são possíveis atualmente via configuração direta no site. Acessando a página [Configurações avançadas](/webchat/configuracoes-avancadas.md) você terá acesso a mais possibilidades para deixar o WebChat com ainda mais cara da sua empresa.