Configuração do Widget de Webchat

O canal de WebChat pode ser disponibilizado de duas formas, e esta página trata apenas da primeira.

Se o cenário exige coletar dados antes da criação do caso, ou criar o caso já com nome, telefone e assunto preenchidos, o widget não atende. Consulte a página de Webchat com formulário de entrada.

Antes de começar

O widget só funciona sobre um canal de WebChat já configurado e ativo. Confirme os itens abaixo antes de escrever qualquer código.

No canal

O canal de WebChat é configurado no caminho Conversação > Canal > WebChat e depende de três cadastros prévios:

1. Unidade de Negócio cadastrada.

2. Conta do provedor de Webchat cadastrada.

3. Tipo de Caso cadastrado.

Horário de atendimento e mensagem fora do expediente também são definidos no canal, e não no objeto de configuração do widget.

Na sua implementação

• O serverDigitalId do canal de WebChat, obtido na tela de canais. Esse identificador é a referência de comunicação do canal. Se o canal for recriado, um novo identificador é gerado e o valor precisa ser atualizado.

• O tenantId correspondente ao seu tenant.

• Um backend próprio, com um endpoint capaz de gerar ou recuperar o sessionId (e as demais credenciais) de forma segura.

• As credenciais de acesso à API da cVortex, utilizadas exclusivamente pelo seu backend.

Por que o backend é necessário

As credenciais de acesso, como Client Secret ou senhas, jamais devem ser expostas diretamente no código client-side da página. A exposição dessas informações pode permitir que terceiros interceptem as chaves e façam requisições indevidas em nome da sua empresa.

A função getCredentials atua exclusivamente como ponto de entrada para consumir um serviço do seu próprio backend. Ela nunca deve conter credenciais.

Como funciona a autenticação

O widget autentica exclusivamente por sessionId:

• Nas chamadas HTTP, o sessionId é enviado no header X-Session-Id.

• No WebSocket, é enviado como query param ?session_id=.

• Não há token de acesso (access_token) nem refresh token. Um sessionId inválido ou expirado é tratado diretamente como erro, sem renovação automática — seu backend precisa fornecer um sessionId válido a cada inicialização.

Referência de configuração

Toda a configuração vive em um único objeto global chamado CVortex, declarado antes do carregamento do script do componente.

Objeto CVortex

Se getCredentials não estiver presente, o componente lança erro e não é inicializado.

Retorno de getCredentials

A Promise deve ser resolvida com um objeto contendo:

Se qualquer um dos três campos obrigatórios (sessionId, tenantId, serverDigitalId) estiver ausente, o widget considera as credenciais inválidas e não autentica.

Objeto Webchat

Todas as propriedades são opcionais.

icon e iconBackgroundColor só têm efeito em conjunto. Se qualquer um faltar, o botão usa o ícone padrão do componente.

Guia de implementação

Passo 1. Declarar o objeto de configuração

Declare o objeto em window antes de carregar o script do componente.

window.CVortex = {
    getCredentials: async () => {
        const response = await fetch("https://seu-backend.com.br/webchat/session", {
            method: "POST"
        });
        const data = await response.json();

        return {
            sessionId: data.sessionId,
            tenantId: data.tenantId,
            serverDigitalId: data.serverDigitalId,
            providerAccountKey: data.providerAccountKey // opcional
        };
    },
    Webchat: {
        title: "Título do Chat",
        icon: "URL_DO_ICONE",
        iconBackgroundColor: "COR_HEXADECIMAL"
    }
};

Use window.CVortex e não var CVortex. Em aplicações que utilizam bundlers, como React ou Vue, uma declaração com var dentro de um módulo permanece no escopo do módulo e não se torna global. O widget não encontra a configuração e não é renderizado.

Passo 2. Implementar o endpoint de sessão no backend

O fluxo de autenticação segue quatro etapas:

1. O widget invoca a função getCredentials no navegador.

2. Sua função realiza uma chamada, por exemplo via fetch, para um endpoint server-side de sua responsabilidade.

3. Seu servidor realiza a autenticação junto à API da cVortex de forma segura e privada, e obtém o sessionId.

4. Seu servidor retorna apenas as credenciais de sessão (sessionId, tenantId, serverDigitalId e, quando aplicável, providerAccountKey) para o frontend, resolvendo a Promise.

O endpoint precisa liberar CORS para a origem da página onde o widget está instalado:

• Access-Control-Allow-Origin com a origem da página

• Access-Control-Allow-Methods com o método utilizado na chamada

• Access-Control-Allow-Headers com os headers enviados pelo frontend

• Resposta ao preflight OPTIONS quando a requisição envia Content-Type: application/json

Passo 3. Adicionar o script e o elemento customizado

<script defer src="https://components.cvortex.com/webchat/cvortex-webchat.js"></script>
<cvortex-webchat></cvortex-webchat>

O script do componente utiliza o atributo defer, o que significa que ele será executado após o carregamento do documento, mas antes do evento DOMContentLoaded. A configuração precisa estar disponível antes da inicialização do script cvortex-webchat.js.

Passo 4. Exemplo completo

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <title>Webchat - Host</title>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <script>
      window.CVortex = {
        getCredentials: async () => {
          const response = await fetch(
            "https://seu-backend.com.br/webchat/session",
            { method: "POST" }
          );
          const data = await response.json();

          return {
            sessionId: data.sessionId,
            tenantId: data.tenantId,
            serverDigitalId: data.serverDigitalId,
            providerAccountKey: data.providerAccountKey
          };
        },

        Webchat: {
          title: "Título Personalizado",
          icon: "https://media.cvortex.io/65bb9354b90287ed5a8dda92/icons/fee9875e23e34c45ea6f67c573c97b0d.jpg",
          iconBackgroundColor: "#fe5000",
          toolbarBackgroundColor: "#fe5000",
          toolbarTextColor: "#ffffff",
          customerBalloonColor: "#2e7d32",
          agentBalloonColor: "#f3e5f5",
          accentColor: "#fe5000"
        }
      };
    </script>

    <script
      defer
      src="https://components.cvortex.com/webchat/cvortex-webchat.js"
    ></script>

    <cvortex-webchat></cvortex-webchat>
  </body>
</html>

Validar a instalação

Execute a validação em ambiente de homologação antes de publicar em produção.

Critérios de sucesso

1. O ícone do chat aparece na página, com a cor de fundo configurada em iconBackgroundColor.

2. Ao clicar no ícone, o painel do chat abre exibindo o valor de title no topo.

3. Na aba Network do navegador, a chamada ao seu endpoint de sessão retorna 200 com sessionId (e os demais campos) no corpo da resposta.

4. É possível enviar uma mensagem pelo widget.

O que checar no console

Se algum critério falhar, abra o console do navegador antes de qualquer outra verificação:

• Erros de carregamento do arquivo cvortex-webchat.js

• Erro getCredentials wasn't found (configuração ausente ou declarada com var)

• Erros de CORS na chamada ao seu endpoint de sessão

• O valor de window.CVortex, para confirmar que a configuração está global e completa

Limitações

• O widget não permite configurar formulário de entrada.

• O widget não permite enviar variáveis para a criação do caso, como nome, telefone ou assunto. Para esse cenário, utilize a página hospedada com formulário de entrada.

• As definições visuais disponíveis são as do objeto Webchat (título, ícone, cores da barra, cores dos balões, imagem de fundo e cor de destaque).

• Não é suportado mais de um widget na mesma página. Não é possível atender múltiplos canais simultaneamente em uma única página.

• O serverDigitalId não é preservado quando o canal é recriado.

• A autenticação é por sessionId, sem refresh: um sessionId inválido ou expirado encerra a sessão.

Uso em WebView e mobile

O widget funciona em WebView. Ainda assim, para WebView e para aplicações mobile a cVortex recomenda a página hospedada com formulário de entrada, e não o widget.