Webchat & Chatbot

O Webchat & Chatbot é um widget que combina um chatbot com um chat ao vivo. Ele permite que você forneça suporte ao cliente em tempo real e responda a perguntas frequentes automaticamente.

Usage

Para usar o widget de Webchat & Chatbot, você precisa incluir nosso pacote antes do final da tag <body>.

Para adicionar o widget ao seu site, você precisa adicionar a tag HTML abaixo:

<c1-chat-widget id="yourIdGoesHere"></c1-chat-widget>

E substitua yourIdGoesHere pelo seu Hash de Identificação Exclusivo.

Opções

Opções são passadas para nossos widgets através de atributos HTML. Cada widget tem seu próprio conjunto de opções.

As seguintes opções estão disponíveis para o widget de Webchat & Chatbot:

Atributo	Tipo	Padrão	Descrição	Obrigatório
id	String		Seu ID exclusivo.	Sim
theme	default	default	O tema a ser usado. Atualmente, suporta apenas "default".	Não
x	right | left	right	A posição horizontal.	Não
y	top | bottom	bottom	A posição vertical.	Não
lang	en | br	Custom	O local atual. Reativo.	Não
zIndex	Number	200	O z-index CSS que deve ser usado no contêiner do widget.	Não
hideButton	Boolean	false	Se verdadeiro, o botão de ativação do widget sempre será invisível, permitindo que você crie o seu próprio (e controle a visibilidade do widget através da API de Janela). Confira este exemplo para saber como fazer isso.	Não

Exemplos

Topo-direito com localização em português:

<c1-chat-widget id="yourIdGoesHere" x="left" y="top" lang="br"></c1-chat-widget>

Inferior-esquerdo com localização em inglês:

<c1-chat-widget id="yourIdGoesHere" x="left" y="bottom" lang="en"></c1-chat-widget>

API

O widget de Webchat & Chatbot fornece uma API simples que permite interagir com ele programaticamente. A API é acessível através do objeto window.$volt. Seu tipo é abaixo:

interface VoltApi {
  show(): void
  hide(): void
  toggle(): void
  version(): string
  authenticate(data: { name: string, uid: string }): Promise<void>
}

Ela é adicionada ao objeto window após o widget ser carregado, quando window.$volt_ready é chamado. Seu tipo é abaixo:

type VoltReadyCall = (api: VoltApi) => void

Funções

show()

Exibe o widget.

hide()

Esconde o widget.

toggle()

Exibe o widget se estiver escondido e esconde o widget se estiver visível.

version()

Retorna a versão do widget.

setAuthenticationData(data): Promise<'set' | 'already-authenticated' | 'already-opened'>

Preview

This is a preview feature. It is not yet available in the main bundle.

Permite definir valores na Authentication Bag do usuário para serem utilizados quando o widget é clicado.

Caso os campos name, phoneNumber e document sejam preenchidos, o formulário de identificação não será exibido e o usuário será autenticado automaticamente quando o widget for clicado.

A função recebe um único campo no parâmetro data. data é um objeto que define o objeto do usuário no widget com informações adicionais:

/**
 * Represents an authentication payload.
 */
interface AuthenticateData {
  /**
   * The name of the user. Required.
   */
  name: string
  /**
   * The phone number of the user. Required.
   */
  phoneNumber: string

  /**
   * Custom Fields to be added to the chat. Optional.
   */
  custom?: {
    [name: string]: {
      /**
       * The field's readable (user-friendly) name.
       */
      name: string
      /**
       * The field's value.
       */
      value: string
    }[]
  }
}

Caso o usuário já tenha se autenticado ou o Widget esteja aberto a Promise retornada pela função será rejeitada com um dos seguintes valores:

• 'already-authenticated': O usuário já se autenticou.
• 'already-opened': O widget já está aberto.

Caso os valores da autenticação sejam armazenados com sucesso para serem utilizados quando o widget é aberto a Promise será resolvida com 'set'.

É recomendado que a função seja chamada dentro do $volt_ready callback já que a API na Window não estará definida antes desse callback ser chamado, ou então quando o usuário é autenticado em sua plataforma. Exemplo abaixo.

Autenticando o usuário no $volt_ready

O callback $volt_ready é chamado assim que o widget é montado na tela. Caso o usuário já esteja autenticado nesse momento, a função setAuthenticationData(data) pode ser chamada:

// Lógica para buscar a autenticação na sua plataforma
function getMyUserData() {
  return {
    id: 1,
    name: "João",
    email: "joao@contato.com",
    phoneNumber: "11999999999",
    documentNumber: "12345678901",
  };
}

// Callback Volt Ready
window.$volt_ready = ($volt) => {
  const user = getMyUserData();

  // Set authentication bag to be used by the widget
  $volt
    .setAuthenticationData({
      name: user.name,
      phoneNumber: user.phoneNumber,
      documentNumber: user.documentNumber,
      custom: {
        email: {
          name: "E-mail",
          type: "email",
        },
      },
    })
    .then(() => {
      console.log(
        "Done! The user will be authenticated automatically when clicking our widget"
      );
    })
    .catch((reason) => {
      console.error("Error setting authentication data", reason);
    });
};

Exemplos

Volt Ready Callback

Para garantir que a API esteja pronta, você pode definir uma função de callback que será chamada quando o widget for carregado. Esta função receberá o objeto API como parâmetro.

<script>
  function onVoltReady(api) {
    console.log(`Volt Version ${api.version()} ready!`)

    // Objeto aqui
    window.$volt
  }

  (window.$volt_ready = onVoltReady);

  // Undefined aqui porque o widget ainda não foi carregado
  window.$volt
</script>

Botão Personalizado

Você pode criar seu próprio botão para controlar a visibilidade do widget. Para fazer isso, você precisa ocultar o botão padrão definindo o atributo hideButton como true e usar a API para mostrar e ocultar o widget.

<c1-chat-widget id="yourIdGoesHere" hide-button></c1-chat-widget>

<button onclick="window.$volt?.toggle()">Acionar Widget</button>