Pular para o conteúdo principal

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:

AtributoTipoPadrãoDescriçãoObrigatório
idStringSeu ID exclusivo.Sim
themedefaultdefaultO tema a ser usado. Atualmente, suporta apenas "default".Não
xright | leftrightA posição horizontal.Não
ytop | bottombottomA posição vertical.Não
langen | brCustomO local atual. Reativo.Não
zIndexNumber200O z-index CSS que deve ser usado no contêiner do widget.Não
hideButtonBooleanfalseSe 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>