Métodos e opções do Web V2

O artigo abaixo fará uma análise aprofundada das possibilidades técnicas do nosso novo widget Web (V2).

A partir de 31 de outubro de 2024, todos os clientes da Chatlayer que usam o canal Web precisarão migrar para o novo widget da web, Web V2. Isso significa que o Web V1 será removido da nossa base de código. Saiba tudo sobre a migração da V1 para a V2.

Todos os métodos

Método	Descrição	Argumentos	Leia mais em
Chatlayer.init()	Inicializa o widget usando as opções especificadas. Este método retorna um objeto semelhante a uma promise.	(opções: Opções)	#Inicialize o widget Web com opções
Chatlayer.open()	Abre o widget.
Chatlayer.close()	Fecha o widget.
Chatlayer.toggle()	Se o widget estiver fechado, ele o abre e vice-versa.
Chatlayer.destroy()	Destrói o widget
Chatlayer.isOpen()	Mostra se o widget está aberto.
Chatlayer.login()	Para federar a identidade do cliente com as do seu site ou aplicativo.	(externalId: string, jwt: string)	#Autenticação do usuário com externalId
Chatlayer.logout()	Fecha a sessão e uma nova conversa começará do zero.	(externalId: string, jwt: string)	#Excluir o histórico do chat
Chatlayer.on()	Assine eventos predefinidos e personalizados durante toda a conversa do usuário com o seu bot.	(evento, (arg1, arg2) => ...)	#Eventos enviados pelo Chatlayer
Chatlayer.off()	Pare de acompanhar ou cancele a inscrição para receber os eventos definidos em Chatlayer.on.
Chatlayer.setLanguage()	Define o idioma atual. Somente idiomas da lista de idiomas suportados pelo seu bot serão aceitos.		#Alterar o idioma
Chatlayer.language()	O idioma atual do widget.		#Alterar o idioma
Chatlayer.setSessionData()	Define dados extras na sessão da conversa e retorna uma promise.		#Definir os dados da sessão
Chatlayer.getCustomer()	Recupera dados da sessão de Internal.user e campos personalizados adicionados a ele.
Chatlayer.sendMessage()	Envia uma mensagem em nome do usuário, por exemplo, se ele clicar em um botão na página.	(texto)
Chatlayer.track()	Cria um novo evento que será rastreado.	ex.: Chatlayer.track ("view_product", product_id: "SKU123"})
Chatlayer.trackEvent()	Acompanhe eventos que ocorrem no seu site ou app.	(eventName: string, eventAttributes: Record<string,any>)
Chatlayer.render()	Este método pode ser usado se você quiser o widget incorporado em uma página.
Chatlayer.startTyping()	Mostra o indicador de digitação	(remetente)
Chatlayer.stopTyping()	Oculta o indicador de digitação ativo
Chatlayer.createConversation()	Inicia uma nova conversa vazia mantendo as informações do cliente
Chatlayer.setDelegate()	Permite definir um delegate personalizado para o avatar e o nome do agente exibidos	DelegateConfig	#Definindo um delegate

---

Inicialize o widget Web com opções

'Chatlayer.init(options: Options)'

Esta função inicializa o widget Web usando as opções especificadas. Este método retorna um objeto semelhante a uma promise.

Observe que, exceto pelos métodos on e off o restante dos métodos documentados abaixo precisa ser chamado após init ser concluído.

Opções

A Opções pode ser:

Opção	É opcional	Valor padrão	Tipo
channelId	Não	-	string	O ID do canal do Chatlayer
título	Sim	-	string	O título a ser exibido no cabeçalho do widget
subtitle	Não	-	string	Um subtítulo opcional para mostrar abaixo do título
position	Não	direita	direita | esquerda	A posição do widget. Os valores possíveis são esquerda ou direita
buttonWidth	Não	58	número	A largura do botão do widget
buttonHeight	Não	58	número	A altura do botão do widget
customColors	Sim	-	CustomColors	Substitua as cores do widget
headerIconUrl	Sim	-	url	URL de uma imagem pública a ser mostrada no cabeçalho
região	Sim	eu-west1-gcp	string	A região da sua conta do Chatlayer
customText	Sim	-	CustomText	Substitua o texto dos diferentes elementos da interface do widget
enableTextInput	Não	verdadeiro	booleano	Defina como false para ocultar a entrada de texto, permitindo que os usuários interajam apenas por meio de botões e respostas rápidas
enableAudioInput	Não	verdadeiro	booleano	Defina como false para ocultar o botão de gravação de áudio, impedindo que os usuários enviem mensagens de áudio pelo widget
enableFileUpload	Não	verdadeiro	booleano	Defina como false para ocultar o botão de envio de arquivos, impedindo que os usuários enviem arquivos pelo widget. A solicitação de envio de arquivo ainda funcionará
enableSoundNotifications	Não	verdadeiro	booleano	Controle se o usuário receberá notificações sonoras sempre que uma nova mensagem chegar. Isso também pode ser alterado pelo usuário nas configurações
prechatForm	Não	-	PrechatForm	Coleta de informações usando um formulário antes do início do chat
delegate	Não	-	DelegateConfig	Defina um delegate para a conversa. Verifique Métodos e opções do Web V2para mais detalhes

customColors

A customColors pode ser:

Opção	Opcional	Valor padrão	Descrição
brandColor	Sim	007171	Esta cor será usada no cabeçalho do messenger e no launcher. Deve ser uma cor hexadecimal de 3 ou 6 caracteres.
conversationColor	Sim	007171	Esta cor será usada para mensagens do cliente, respostas rápidas e ações no rodapé.
actionColor	Sim	007171	Esta cor será usada para call-to-actions dentro das suas mensagens. Deve ser uma cor hexadecimal de 3 ou 6 caracteres.

customText

customText pode ser:

Opção	Opcional	Valor padrão	Descrição
inputPlaceholder	Sim	Enviar uma mensagem	Texto de placeholder exibido no campo de entrada da mensagem
botDisplayName	Sim	Bot	Este é o nome de exibição do bot. Use uma string vazia para ocultá-lo.
agentDisplayName	Sim	Agente	Este é o nome de exibição do agente. Use uma string vazia para ocultá-lo.

Para fornecer valores diferentes para idiomas diferentes, adicione um subcampo com o código do idioma.

prechatForm

O prechatForm é uma das opções que temos no widget Web para configurar um formulário com um conjunto de campos de entrada antes de iniciar o chat.

Internamente, consiste em uma matriz de definições de elementos. Cada elemento pode ter o seguinte tipo, rótulo, placeholder e variante.

Nome	Tipo	Descrição	Aplica-se a
tipo	String	O tipo de elemento	Um dos text, spacer, input, select, checkbox, botão, textarea, image
rótulo	String	O texto que aparece acima do campo de entrada	input, textarea, select, checkbox
placeholder	String	O texto de exemplo no campo	input, textarea, select, checkbox
variante	String	A variante do elemento	Um dos primária, secundária | botão

Exemplo de código de como usar prechatForm e seus elementos

// Exemplo de código que mostra como usar prechatForm e seus elementos.  
<script type="application/javascript">Chatlayer.init(Chatlayer.init({"channelId": "YOUR_CHANNEL_ID", "region": "eu-west1-gcp", "position": "right", 
            "prechatForm": {
            elements: [
              {
                id: 'age',
                type: 'input',
                label: 'Idade',
                required: true,
                variant: 'number',
                placeholder: 'Texto de placeholder...',
              },
              {
                id: 'email',
                type: 'input',
                variant: 'email',
                label: 'E-mail',
                defaultValue: '[e-mail]',
                placeholder: 'Texto de placeholder...',
              },
              {
                id: 'website',
                type: 'input',
                label: 'Site da empresa',
                placeholder: 'Texto de placeholder...',
              },
              {
                type: 'select',
                id: 'checkbox-1',
                label: 'Rótulo da seleção',
                placeholder: 'Selecione o tamanho da empresa',
                options: [
                  {
                    id: 'option-1',
                    type: 'option',
                    label: 'Opção 1',
                  },
                  {
                    id: 'option-2',
                    type: 'option',
                    label: 'Opção 2',
                  },
                  {
                    id: 'option-3',
                    type: 'option',
                    label: 'Opção 3 (Desativada)',
                    disabled: true,
                  },
                ],
              },
              {
                type: 'spacer',
                size: 'md',
              },
              {
                type: 'text',
                text: 'Saiba mais [aqui](https://google.com)',
              },
              {
                type: 'checkbox',
                id: 'checkbox-2',
                // label: 'Rótulo da seleção',
                required: true,
                placeholder: 'Selecione o tamanho da empresa',
                options: [
                  {
                    id: 'option-1',
                    type: 'option',
                    required: true,
                    label: 'Aceitar termos e condições',
                  },
                ],
              },
            ],
          }                                        
})</script> 

Abaixo, um exemplo de prévia de como PrechatForm aparece no widget. O usuário pode personalizar os campos antes de iniciar o chat.

exemplo de prechatForm.

Outros métodos

Autenticação do usuário com externalId

Quando o widget é inicializado, um cliente anônimo é criado automaticamente. Esse cliente pode então enviar mensagens para o bot.

Em alguns cenários, você pode querer federar a identidade do cliente com a do seu site ou aplicativo. Isso é feito usando o externalId. Este campo identifica o usuário no seu sistema. Pode ser um endereço de e-mail, um nome de usuário, um uuid ou qualquer outro ID de usuário no seu banco de dados. O mais importante é que seja único e sempre referencie uma entidade do seu sistema.

Para comprovar a autenticidade do usuário, exigimos um token JWT assinado que valide a propriedade do widget. Caso contrário, qualquer pessoa pode se passar pelos seus usuários.

Criar um token JWT assinado

Para criar um token JWT assinado:

1. Faça login na sua conta do Chatlayer.

2. Crie um token de acesso em: https://app.chatlayer.ai/settings/api-access/tokens

3. O token terá o formato [keyId]:[keySecret]. Observe que há : separando as duas partes do token.

4. Implemente código no lado do servidor para assinar novos JWTs usando okeyId e keySecret. O cabeçalho do JWT deve especificar o ID da chave no campo kid . A carga útil do JWT deve incluir uma channel_id declaração na carga útil do jwt e uma sub declaração que deve ser definida como o ID externo do usuário.

Um exemplo em node.js é fornecido abaixo usando jsonwebtoken >= 6.0.0:

var jwt = require('jsonwebtoken');
// dado o token 647f1ecd48f7f8aa3abe17fd:5e39a6051B53e7Cf92CF0dB9F2Bd5Eb0
var KEY_ID = '647f1ecd48f7f8aa3abe17fd';
var KEY_SECRET = '5e39a6051B53e7Cf92CF0dB9F2Bd5Eb0';
var CHANNEL_ID = 'liiq8woe:647f1f0910f7d21246e1df75';

var signJwt = function (userId) {
  return jwt.sign(
    {
      channel_id: CHANNEL_ID,
      sub: userId,
    },
    KEY_SECRET,
    {
      header: {
        alg: 'HS256',
        typ: 'JWT',
        kid: KEY_ID,
      },
    }
  );
};

1. Do seu site, chame:

Chatlayer.login(externalUserId, signedJWT).then(() => {
  // usuário autenticado
  }, err => {
// ocorreu um erro
  })`

método	informações necessárias
Chatlayer.login()	(externalId: string, jwt: string)
Chatlayer.logout()	(externalId: string, jwt: string)

Excluir o histórico do chat

Nosso novo widget, por padrão, armazena todas as conversas entre o bot e o cliente. Isso garante uma experiência semelhante à de outras plataformas de mensagens. Quando os usuários entram em contato com o bot pelo widget e o reabrem, eles podem visualizar todas as conversas anteriores por padrão.

Se você quiser contornar isso ou quiser que os clientes possam atualizar a conversa, você pode usar nossos chatlayer.login ou chatlayer.logout comandos para permitir isso.

Criar um botão de atualização

O script abaixo permitirá adicionar um botão ao seu widget que, ao ser clicado, limpará a conversa. O botão terá o id: RESTART_CONVERSATION e, ao ser clicado, fará logout do usuário e fará login novamente imediatamente.

Certifique-se de que a constante esteja definida primeiro:

const RESTART_CONVERSATION = 'restart-conversation';

"customActions" deve ser uma propriedade do objeto usado para o método Chatlayer.init:

O próprio botão (para adicionar na seção do cabeçalho):
  customActions: [
            {
              id: RESTART_CONVERSATION,
              label: 'Reiniciar conversa'
              image:
                "data:image/svg+xml,%3Csvg xmlns='' height='24' width='24'%3E%3Cpath d='M12 5V2L8 6l4 4V7c3.31 0 6 2.69 6 6 0 2.97-2.17 5.43-5 5.91v2.02c3.95-.49 7-3.85 7-7.93 0-4.42-3.58-8-8-8zM6 13c0-1.65.67-3.15 1.76-4.24L6.34 7.34A8.014 8.014 0 0 0 4 13c0 4.08 3.05 7.44 7 7.93v-2.02c-2.83-.48-5-2.94-5-5.91z' fill='white' /%3E%3C/svg%3E",
            },
          ]

rótuloé um campo opcional disponível para cada CustomAction, ele é usado como aria-label de um elemento e é importante para aumentar a acessibilidade do seu widget.

O listener para "widget:custom_action" deve ser adicionado após a inicialização:

Chatlayer.on('widget:custom_action', async ({ id }) => {
              console.log('callback do manipulador do evento widget:custom_action', { id });
              if (id === RESTART_CONVERSATION) {
                await window.Chatlayer.logout();
                await window.Chatlayer.login();
              }
            });

O trecho completo do código ficaria parecido com este exemplo:

const RESTART_CONVERSATION = 'restart-conversation';

Chatlayer.init(
  {"channelId": "xxxxxxxxx", 
  "region": "xx-xxxx-xx", 
  "position": "xxxxxx",
  "customActions": [
            {
              id: RESTART_CONVERSATION,
              image:
                "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' height='24' width='24'%3E%3Cpath d='M12 5V2L8 6l4 4V7c3.31 0 6 2.69 6 6 0 2.97-2.17 5.43-5 5.91v2.02c3.95-.49 7-3.85 7-7.93 0-4.42-3.58-8-8-8zM6 13c0-1.65.67-3.15 1.76-4.24L6.34 7.34A8.014 8.014 0 0 0 4 13c0 4.08 3.05 7.44 7 7.93v-2.02c-2.83-.48-5-2.94-5-5.91z' fill='white' /%3E%3C/svg%3E",
            },
          ]
  }
).then(() => {
	Chatlayer.on('widget:custom_action', async ({ id }) => {
              console.log('callback do manipulador do evento widget:custom_action', { id });
              if (id === RESTART_CONVERSATION) {
                await window.Chatlayer.logout();
                await window.Chatlayer.login();
              }
            });
})

Eventos enviados pelo Chatlayer

Chatlayer.on(event, (arg1, arg2) => ...)

event	descrição	arg1
widget:opened	O widget foi aberto	-
widget:closed	O widget foi fechado	-
widget:custom_action	Quando um botão de ação personalizada foi clicado	-
message:received	Uma mensagem foi recebida	-
message:sent	Uma mensagem foi enviada pelo usuário	-
event:received	Um evento foi recebido	EventPayload
init	O widget foi inicializado	-
destroy	O widget foi destruído	-

EventPayload

Field	Tipo	Descrição
generic_event	GenericEvent	Um evento genérico
agent_joined_event	AgentJoinedEvent	Quando um agente entra na conversa
agent_left_event	AgentLeftEvent	Quando um agente sai da conversa

GenericEvent

Field	Tipo	Descrição
payload	JSON	Dados arbitrários definidos para o evento. Um objeto JSON válido.

Observe que você pode usar o JSON Builder para enviar eventos genéricos da sessão do seu usuário para o site em que você hospedou o widget.

AgentJoinedEvent

Field	Tipo	Descrição
agente	Agente	Representa um agente envolvido em uma conversa.

Agente

Field	Tipo	Descrição
display_name	string	Nome de exibição do agente
picture_url	string	URL da imagem do agente.
tipo	AgentType	A classificação do agente pode ser UNKNOWN_AGENT_TYPE, HUMAN ou BOT.

Use Chatlayer.off(event, (arg1, arg2) => ...)para cancelar a inscrição desses eventos.

Alterar o idioma

Chatlayer.setLanguage(language)

Define o idioma atual. Apenas os idiomas na lista de idiomas suportados pelo seu bot serão aceitos.

Chatlayer.language

É o idioma atual do widget.

Observe que você também pode alterar o idioma do bot usando o iframe em Instalação guia.

Defina os dados da sessão

Se você quiser transferir dados do seu site para o chatbot, você pode adicionar esses dados à chatlayer função após inicializar o widget. Todos os dados serão colocados na sessão do Chatlayer. Esses dados podem então ser usados para personalizar o fluxo do chatbot com base em dados reais do site.

Chatlayer.setSessionData(SessionData)

Define dados extras na sessão da conversa e retorna uma promessa

Exemplo

Chatlayer.setSessionData({
  Product: 'iPhone XS',
  });
// ou
Chatlayer.setSessionData('Product', 'iPhone XS');

O exemplo acima mostra como você pode definir a variável Product na sessão do Chatlayer. Ele receberá o valor iPhone XS neste caso.

Definindo um delegate

O widget permite que você defina um delegate para receber callbacks quando mudanças importantes acontecerem na conversa. Para definir um delegate, passe o parâmetro delegate nas opções de inicialização ou use o método setDelegate. O objeto delegate pode conter opcionalmente as funções beforeDisplay ou beforeSend.

Passar delegate como parte das opções de inicialização é o método preferido. O método setDelegate pode ser usado para alterar ou remover comportamentos do delegate depois que uma conversa tiver sido inicializada.

const delegate = {
  beforeDisplay(message) {
    if (data.sender.type === 'agent') {
      message.sender.display_name = 'John Doe';
    }
    return message;
  },
  beforeSend(message) {
    return message;
  },
};
 
// Passando delegate como parâmetro de inicialização
Chatlayer.init({
  channelId: '<channel-id>',
  delegate,
});
 
// Usando setDelegate
Chatlayer.init({ integrationId: '<channel-id>' }).then(() => {
  Chatlayer.setDelegate(delegate);
});

DelegateConfig

DelegateConfig é um objeto contendo os 2 campos abaixo:

beforeDisplay

A beforeDisplay O delegate permite que uma mensagem seja ocultada ou modificada antes de ser exibida na conversa. Este delegate deve retornar um valor falsy, como null, para ocultar a mensagem. Ele também pode retornar um objeto de mensagem modificado para alterar o que o usuário verá renderizado no histórico da conversa. Observe que essa alteração afeta apenas a renderização no lado do cliente; a cópia dessa mensagem no lado do servidor não pode ser modificada por este delegate.

beforeSend

A beforeSend O método delegate permite modificar as propriedades de uma mensagem antes de enviá-la ao Chatlayer. A mensagem modificada deve ser retornada para que a alteração tenha efeito.

Um uso comum deste método é adicionar metadados à mensagem.

Observe que, quando um arquivo ou uma imagem é enviado, apenas os metadados da mensagem podem ser atualizados. Outras propriedades da mensagem, como tipo ou texto, não serão consideradas.

---

💬 Dê feedback

Por favor, nos diga o que você acha do novo widget Web aqui.