Essa funcionalidade permite que o Widget seja migrado para uma versão mais segura, utilizando autenticação por token via WebSocket. Isso evita o uso direto do identifier na URL e aumenta a proteção das sessões.

Importante: Essa implementação exige o suporte de um desenvolvedor backend da sua equipe.

Etapa 1 – Solicite a ativação da funcionalidade

Antes de iniciar a configuração, é necessário ativar a funcionalidade no seu ambiente. Para isso, você ou o responsável pela sua conta pode abrir um chamado para a nossa equipe: 

1. Acesse este formulário de solicitação.

2. No campo de Resumo, você pode utilizar Ativação do Widget Seguro. 

3. Na Descrição, solicite a ativação do addon auth_widget.

4. Em seguida, ative na configuração do Widget a autenticação: Acesse Connect > Canais > Widgets > Editar Widget > Na aba de Autenticação, marque a caixa de seleção conforme imagem abaixo:

Após a ativação, você receberá:

• Credenciais de autenticação

• URL para aquisição do token

Atenção: Uma vez ativada a autenticação via token no Widget, não será possível desativá-la. Certifique-se de concluir todas as etapas de implementação antes de realizar a ativação.

Etapa 2 – Configure sua API segura

Sua equipe técnica deverá desenvolver uma API backend responsável por adquirir o token de autenticação. Essa API será responsável por:

• Fazer uma requisição GET para a URL fornecida pela Zenvia.

• Enviar as credenciais recebidas no cabeçalho da requisição (headers).

• Retornar o token no formato esperado

Exemplo de headers:

auth-key: xxxxxxxxxxxxx

auth-password: xxxxxxxxxxxxx

Exemplo de resposta esperada (JSON):

{
  "token": "json web token"
}

Importante: 🕒 O token gerado tem validade de 5 minutos. Ele deve ser utilizado imediatamente na abertura do Widget.

Etapa 3 – Configure o token

1. Acesse a aba Aparência e Comportamento na edição do seu Widget.

2. Insira a função getAccessToken no campo de script personalizado, conforme imagem:

Exemplo de implementação:

<script>
    async function getAccessToken(previousToken) {
        const response = await fetch("https://suaapi.com", {
            method: "POST",
            headers: {
                "Content-Type": "application/json"
            },
            body: JSON.stringify({
                token: previousToken // obrigatório em caso de reconexão
            })
        });
        const data = await response.json();
        return data.token;
    }
</script>

Etapa 4 – Reconexão do Widget

Quando o Widget tentar se reconectar automaticamente, ele enviará o token anterior como argumento da função getAccessToken.

Sua API deverá considerar esse token para gerar e retornar um novo JWT válido.

Exemplo de body da requisição na reconexão:

{
  "token": "json web token"
}

Importante: O novo token deve ser gerado a partir do anterior e respeitar os critérios de segurança definidos pela sua equipe técnica.

Tratamento de erros

• Se o token for inválido na primeira tentativa de conexão, o Widget não inicializa. O usuário verá uma mensagem de erro “Este canal está passando por instabilidade”. Essa mensagem é padrão para quando não conecta, mas poderá ser customizada. 

• Se o erro ocorrer na reconexão, o Widget será desconectado automaticamente.

• É possível você implementar ajustes para minimizar falhas, como tratamento de timeouts e renovação de token antes do vencimento.

Posso testar antes de ativar em produção?

Sim. Nossa recomendação é:

1. Crie um Widget exclusivo para testes.
2. Faça toda a implementação da autenticação nesse ambiente isolado
3. Não ative a autenticação em um Widget que já esteja em uso com alto volume sem ter a implementação concluída pois isso pode causar indisponibilidade.

Boas práticas de segurança

• Nunca exponha suas credenciais de autenticação no frontend.

• Toda a lógica para aquisição do token deve estar protegida em uma API backend.

• Garanta que sua API gere um novo token sempre que o anterior expirar ou for inválido.

Após ativar a autenticação via token, não será possível desativá-la.