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, 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.

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.

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:

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:

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:

window.cbAsyncInit = function () {
    CBM.ChatbotId = "cbXXXX"; // ID da Suri
};

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

• StartWebChat

• UpdateUser

• OnReceiveMessage

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.

  • 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.

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

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.

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:

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 => { /* ... */ });
}

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.

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:

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 você terá acesso a mais possibilidades para deixar o WebChat com ainda mais cara da sua empresa.