🆕Métodos e opções do Web V2

O artigo abaixo aprofundará as 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 mudar para o novo widget web, Web V2. Isso significa que o Web V1 será removido da nossa base de código. Saiba tudo sobre migrar do V1 para o V2.

Todos os métodos

Método

Descrição

Argumentos

Opções

O Opções pode ser:

Opção

É opcional

Valor padrão

Tipo

channelId

Não

string

O ID do canal Chatlayer

title

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

posição

Não

direita

direita | esquerda

A posição do widget. Os valores possíveis são esquerda ou direita

buttonWidth

Não

número

A largura do botão do widget

buttonHeight

Não

número

A altura do botão do widget

customColors

Sim

CoresPersonalizadas

Substituir as cores do widget

headerIconUrl

Sim

url

URL de uma imagem pública a ser exibida no cabeçalho

região

Sim

eu-west1-gcp

string

A região da sua conta Chatlayer

customText

Sim

TextoPersonalizado

Substituir o texto dos diferentes elementos da UI do widget

enableTextInput

Não

verdadeiro

booleano

Defina como false para ocultar o campo de entrada de texto, permitindo que os usuários interajam apenas via 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 upload de arquivo, impedindo que os usuários enviem arquivos pelo widget. A solicitação de upload de arquivo ainda funcionará

enableSoundNotifications

Não

verdadeiro

booleano

Controla se o usuário receberá notificações sonoras toda vez que uma nova mensagem chegar. 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

O 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 lançador. 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 chamadas à ação dentro de 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 placeholder exibido no campo de entrada de mensagem

botDisplayName

Sim

Bot

Este nome de exibição do bot. Use uma string vazia para ocultá-lo.

agentDisplayName

Sim

Agente

Este 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 começar o chat.

Internamente, consiste em um array de Definições de Elemento. Cada elemento pode ter o seguinte type, rótulo, placeholder e variantes.

Nome

Tipo

Descrição

Aplica-se a

type

String

O tipo de elemento

Um de text, espaçador, entrada, selecionar, caixa de seleção, rótulo, área de texto, imagem

rótulo

String

O texto que vai acima do campo de entrada

entrada, área de texto, selecionar, caixa de seleção

placeholder

String

O texto de exemplo no campo

entrada, área de texto, selecionar, caixa de seleção

variantes

String

A variante do elemento

Um de primário, secundário | rótulo

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": "SEU_CHANNEL_ID", "region": "eu-west1-gcp", "position": "right", 
            "prechatForm": {
            elements: [
              {
                id: 'age',
                type: 'input',
                label: 'Age',
                required: true,
                variant: 'number',
                placeholder: 'Placeholder text...',
              },
              {
                id: 'email',
                type: 'input',
                variant: 'email',
                label: 'Email',
                defaultValue: '[email protected]',
                placeholder: 'Placeholder text...',
              },
              {
                id: 'website',
                type: 'input',
                label: 'Company website',
                placeholder: 'Placeholder text...',
              },
              {
                type: 'select',
                id: 'checkbox-1',
                label: 'Select Label',
                placeholder: 'Select company size',
                options: [
                  {
                    id: 'option-1',
                    type: 'option',
                    label: 'Option 1',
                  },
                  {
                    id: 'option-2',
                    type: 'option',
                    label: 'Option 2',
                  },
                  {
                    id: 'option-3',
                    type: 'option',
                    label: 'Option 3 (Disabled)',
                    disabled: true,
                  },
                ],
              },
              {
                type: 'spacer',
                size: 'md',
              },
              {
                type: 'text',
                text: 'Learn more [here](https://google.com)',
              },
              {
                type: 'checkbox',
                id: 'checkbox-2',
                // label: 'Select Label',
                required: true,
                placeholder: 'Select company size',
                options: [
                  {
                    id: 'option-1',
                    type: 'option',
                    required: true,
                    label: 'Accept Terms and conditions',
                  },
                ],
              },
            ],
          }                                        
})</script>

Abaixo, um exemplo de pré-visualização de como PrechatForm parece no widget. O usuário pode personalizar os campos antes de iniciar o chat.

Outros métodos

Autenticação de 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 aplicação. 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 sua propriedade do widget. Caso contrário, qualquer pessoa pode se passar por seus usuários.

Criar um token JWT assinado

Para criar um token JWT assinado:

Faça login na sua conta Chatlayer.
Crie um token de acesso em: https://app.chatlayer.ai/settings/api-access/tokens
O token terá a forma de [keyId]:[keySecret]. Observe que há : separando as duas partes do token.
Implemente código no lado servidor para assinar novos JWTs usando okeyId e keySecret. O cabeçalho do JWT deve especificar o ID da chave no kid campo. O payload do JWT deve incluir uma channel_id claim no payload do jwt e um sub claim que deve ser definido como seu id externo do usuário.

Abaixo é fornecido um exemplo em node.js usando jsonwebtoken >= 6.0.0:

var jwt = require('jsonwebtoken');
// given 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,
      },
    }
  );
};

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 a outras plataformas de mensagens. Quando os usuários contatam o bot pelo widget e o reabrem, eles podem ver todas as conversas anteriores por padrão.

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

Criar um botão de atualização

O script abaixo permite que você adicione 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á o logout do usuário e o logará 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: 'Restart conversation'
              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, é usado para 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 de evento widget:custom_action', { id });
              if (id === RESTART_CONVERSATION) {
                await window.Chatlayer.logout();
                await window.Chatlayer.login();
              }
            });

Trecho de código completo seria 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 de 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) => ...)`

evento

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 customizada 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

Campo

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

Campo

Tipo

Descrição

payload

JSON

Dados arbitrários definidos para o evento. Um objeto JSON válido.

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

AgentJoinedEvent

Campo

Tipo

Descrição

agente

Agente

Representa um agente envolvido em uma conversa.

Agente

Campo

Tipo

Descrição

display_name

string

Nome de exibição do agente

picture_url

string

A URL da foto do Agente.

type

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. Somente idiomas na lista de idiomas suportados pelo seu bot serão aceitos.

`Chatlayer.language`

É o idioma atual no widget.

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

Definir os dados da sessão

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

`Chatlayer.setSessionData(SessionData)`

Define dados extras na sessão de conversa e retorna uma promise

Exemplo

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

O exemplo acima mostra como você pode definir a variável Produto na sessão do Chatlayer. Ela 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 ocorrerem na conversa. Para definir um delegate, passe o parâmetro delegate nas opções de init, ou use o método setDelegate. O objeto delegate pode opcionalmente conter funções beforeDisplay ou beforeSend.

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

const delegate = {
  beforeDisplay(message) {
    if (data.sender.type === 'agent') {
      message.sender.display_name = 'John Doe';
    }
    return message;
  },
  beforeSend(message) {
    return message;
  },
};
 
// Passando o delegate como parâmetro de init
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

O beforeDisplay 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 cliente; a cópia do servidor dessa mensagem não pode ser modificada por este delegate.

beforeSend

O beforeSend o método delegate permite que você modifique 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 desse método é adicionar metadados à mensagem.

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

💬 Dar feedback

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

PreviousDo Web V1 para o V2 NextSinch Conversation API

Last updated 2 months ago

Was this helpful?

Todos os métodos

Inicialize o widget Web com opções

Opções

customColors

customText

prechatForm

Outros métodos

Autenticação de usuário com externalId

Excluir o histórico do chat

Criar um botão de atualização

Eventos enviados pelo Chatlayer

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

Alterar o idioma

Chatlayer.setLanguage(language)

Chatlayer.language

Definir os dados da sessão

Chatlayer.setSessionData(SessionData)

Definindo um delegate

DelegateConfig

beforeDisplay

beforeSend

💬 Dar feedback

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

`Chatlayer.setLanguage(language)`

`Chatlayer.language`

`Chatlayer.setSessionData(SessionData)`