For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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)

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)

Chatlayer.logout()

Fecha a sessão e uma nova conversa começará do zero.

(externalId: string, jwt: string)

Chatlayer.on()

Assine eventos predefinidos e personalizados durante toda a conversa do usuário com o seu bot.

(evento, (arg1, arg2) => ...)

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.

Chatlayer.language()

O idioma atual do widget.

Chatlayer.setSessionData()

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

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


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.

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

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

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

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

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:

  1. Do seu site, chame:

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:

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

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:

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

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

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.

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

Atualizado

Isto foi útil?