Implementação JWT Zendesk Messaging do Zero

Visão Geral

O JWT (JSON Web Token) permite que usuários logados no seu sistema acessem automaticamente o chat do Zendesk sem precisar fazer login novamente. É como uma "chave digital" que prova que o usuário já foi autenticado.

Fluxo básico:

Usuário está logado no seu site
Abre o chat do Zendesk
JavaScript pega dados do usuário logado
Envia para seu servidor que gera um JWT
JWT é enviado para o Zendesk
Usuário fica automaticamente logado no chat

PASSO 1: Configuração no Admin Zendesk

1 Criar Configuração JWT

Acesse Admin Center → Conta → Segurança → Autenticação de usuário final
Clique "Criar Chave"
Dê o Nome
Anote o "Segredo compartilhado" e "Key ID" gerados

PASSO 2: Backend PHP (Servidor)

Crie o arquivo zendesk-jwt.php no seu servidor:

php

<?php
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: POST, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type');

// Tratar OPTIONS (CORS)
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    exit;
}

// Só aceitar POST
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['error' => 'Método não permitido']);
    exit;
}

// Receber dados do usuário
$input = file_get_contents('php://input');
$data = json_decode($input, true);

if (!isset($data['email']) || empty($data['email'])) {
    http_response_code(400);
    echo json_encode(['error' => 'Email obrigatório']);
    exit;
}

// SUAS CREDENCIAIS ZENDESK (obtidas no Passo 1)
$jwt_secret = 'SEU_SEGREDO_COMPARTILHADO_AQUI';
$key_id = 'SEU_KEY_ID_AQUI';

$user_email = $data['email'];
$user_name = $data['name'] ?? $user_email;
$external_id = 'user_' . hash('sha256', $user_email);

// Timestamps
$current_time = time();
$expiration_time = $current_time + (60 * 60); // 1 hora

// Payload JWT - CAMPOS OBRIGATÓRIOS
$payload = [
    'external_id' => $external_id,
    'scope' => 'user',                    // OBRIGATÓRIO para Messaging
    'name' => $user_name,
    'email' => $user_email,
    'email_verified' => true,             // OBRIGATÓRIO
    'iat' => $current_time,               // OBRIGATÓRIO
    'exp' => $expiration_time,            // OBRIGATÓRIO
    'jti' => uniqid() . mt_rand(1000, 9999) // OBRIGATÓRIO (anti-replay)
];

// Funções JWT
function base64url_encode($data) {
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function generateJWT($payload, $secret, $key_id) {
    $header = [
        'typ' => 'JWT',
        'alg' => 'HS256',
        'kid' => $key_id
    ];
    
    $headerEncoded = base64url_encode(json_encode($header));
    $payloadEncoded = base64url_encode(json_encode($payload));
    $signature = hash_hmac('sha256', "$headerEncoded.$payloadEncoded", $secret, true);
    
    return "$headerEncoded.$payloadEncoded." . base64url_encode($signature);
}

// Gerar e retornar JWT
$jwt_token = generateJWT($payload, $jwt_secret, $key_id);

echo json_encode(['jwt' => $jwt_token]);
?>

PASSO 3: Frontend JavaScript

Adicione este código onde o Zendesk Widget carrega (geralmente no final do <body>):

javascript

// AUTENTICAÇÃO AUTOMÁTICA PARA ZENDESK GUIDE
console.log('🚀 Iniciando autenticação Zendesk Guide');

// Verificar se usuário está logado no Guide
function isUserLoggedInGuide() {
    return window.HelpCenter && HelpCenter.user && HelpCenter.user.email;
}

function waitForZendesk(callback) {
    if (typeof zE !== 'undefined') {
        callback();
    } else {
        setTimeout(() => waitForZendesk(callback), 100);
    }
}

// FUNÇÃO QUE BUSCA JWT DO SEU SERVIDOR
function authenticateUser(callback) {
    console.log('🔐 Zendesk solicitou autenticação');
    
    // Verificar se usuário está logado no Guide
    if (!isUserLoggedInGuide()) {
        console.error('❌ Usuário não está logado no Guide');
        callback(null);
        return;
    }

    const userData = {
        email: HelpCenter.user.email,
        name: HelpCenter.user.name || HelpCenter.user.email
    };

    console.log('📤 Enviando dados do usuário:', userData);
    
    fetch('https://dominio.com.br/zendesk-jwt.php', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(userData)
    })
    .then(response => {
        console.log('📡 Status da resposta:', response.status);
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        return response.json();
    })
    .then(data => {
        console.log('✅ Resposta do backend:', data);
        
        if (data.jwt) {
            console.log('🔑 JWT recebido com sucesso');
            callback(data.jwt);
        } else {
            console.error('❌ JWT não encontrado na resposta');
            callback(null);
        }
    })
    .catch(error => {
        console.error('❌ Erro ao buscar JWT:', error);
        callback(null);
    });
}

// INICIALIZAR QUANDO TUDO ESTIVER PRONTO
function initializeAuth() {
    if (!isUserLoggedInGuide()) {
        console.log('👤 Usuário não está logado - não configurando autenticação');
        return;
    }

    console.log('👤 Usuário logado:', {
        email: HelpCenter.user.email,
        name: HelpCenter.user.name,
        id: HelpCenter.user.id
    });

    // CONFIGURAR AUTENTICAÇÃO PARA WEB WIDGET CLÁSSICO
    window.zESettings = {
        webWidget: {
            authenticate: {
                jwtFn: authenticateUser
            }
        }
    };
    console.log('⚙️ zESettings configurado para Web Widget clássico');

    // AGUARDAR zE E CONFIGURAR MESSAGING (se disponível)
    waitForZendesk(function() {
        console.log('✅ Zendesk carregado');
        
        try {
            // Tentar configurar para o novo Messaging
            zE('messenger', 'loginUser', authenticateUser);
            console.log('✅ Messaging authentication configurado');
        } catch (error) {
            console.log('⚠️ Messaging não disponível, usando apenas Web Widget clássico');
            console.log('⚠️ Erro:', error.message);
        }

        // Log final
        console.log('🎯 Autenticação Zendesk configurada com sucesso!');
    });
}

// AGUARDAR HELPCENTENTER E ZENDESK ESTAREM PRONTOS
function waitForHelpCenter(callback, attempt = 0) {
    if (window.HelpCenter && typeof zE !== 'undefined') {
        callback();
    } else if (attempt < 50) {
        setTimeout(() => waitForHelpCenter(callback, attempt + 1), 200);
    } else {
        console.error('❌ Timeout aguardando HelpCenter ou zE');
    }
}

// INICIAR O PROCESSO
waitForHelpCenter(initializeAuth);

// FUNÇÃO DE DEBUG (opcional)
window.debugZendeskAuth = function() {
    console.log('🔧 === DEBUG ZENDESK AUTH ===');
    console.log('HelpCenter disponível:', !!window.HelpCenter);
    console.log('zE disponível:', typeof zE);
    console.log('Usuário logado:', isUserLoggedInGuide());
    
    if (isUserLoggedInGuide()) {
        console.log('Dados do usuário:', {
            email: HelpCenter.user.email,
            name: HelpCenter.user.name,
            id: HelpCenter.user.id
        });
        
        // Testar autenticação manualmente
        authenticateUser(function(jwt) {
            if (jwt) {
                console.log('✅ Teste de autenticação bem-sucedido');
            } else {
                console.log('❌ Teste de autenticação falhou');
            }
        });
    }
};

PASSO 4: Configuração das Variáveis de Usuário

Você precisa ter as informações do usuário logado disponíveis no JavaScript. Exemplo em PHP:

php

<!-- No HTML da sua página -->
<script>
    // Definir variáveis globais com dados do usuário logado
    window.USER_EMAIL = '<?php echo $_SESSION['user_email']; ?>';
    window.USER_NAME = '<?php echo $_SESSION['user_name']; ?>';
</script>

PASSO 5: Teste e Debug

5.1 Teste Simples

javascript

// Executar no console do navegador
console.log('Usuário:', window.USER_EMAIL);
console.log('zE disponível:', typeof zE);

5.2 Teste do JWT

Acesse https://seudominio.com/zendesk-jwt.php via POST
Copie o JWT retornado
Cole em jwt.io para verificar se está válido

5.3 Verificar Logs

Backend: arquivo de log no servidor
Frontend: console do navegador

Possíveis Problemas e Soluções

Problema: "Callback não é executado"

Solução: Verificar se zE está carregado antes de configurar

Problema: "JWT inválido"

Soluções:

Verificar se kid no header corresponde ao Key ID do admin
Confirmar se exp não está expirado
Validar segredo compartilhado

Problema: "CORS error"

Solução: Adicionar headers CORS no PHP (já incluído no exemplo)

Problema: "Usuário não aparece como logado"

Soluções:

Verificar se email_verified: true
Confirmar se scope: 'user'
Validar se email existe no payload

Checklist de Implementação

Backend

Arquivo PHP criado e acessível
Credenciais JWT configuradas (secret + key_id)
Headers CORS configurados
Payload com campos obrigatórios

Admin Zendesk

Configuração JWT criada
URL do backend configurada
SSO ativado para usuários finais
Credenciais anotadas

Frontend

Variáveis de usuário disponíveis
Função authenticateUser implementada
Configuração zE('messenger', 'loginUser') adicionada
Aguardo do zE estar disponível

Teste

JWT válido gerado
Console sem erros
Usuário aparece logado no chat
Funciona para diferentes usuários

Artigos nessa seção

Visão Geral

PASSO 1: Configuração no Admin Zendesk

1 Criar Configuração JWT

PASSO 2: Backend PHP (Servidor)

PASSO 3: Frontend JavaScript

PASSO 4: Configuração das Variáveis de Usuário

PASSO 5: Teste e Debug

5.1 Teste Simples

5.2 Teste do JWT

5.3 Verificar Logs

Possíveis Problemas e Soluções

Problema: "Callback não é executado"

Problema: "JWT inválido"

Problema: "CORS error"

Problema: "Usuário não aparece como logado"

Checklist de Implementação

Backend

Admin Zendesk

Frontend

Teste

Comentários

Artigos nessa seção

Visão Geral

PASSO 1: Configuração no Admin Zendesk

1 Criar Configuração JWT

PASSO 2: Backend PHP (Servidor)

PASSO 3: Frontend JavaScript

PASSO 4: Configuração das Variáveis de Usuário

PASSO 5: Teste e Debug

5.1 Teste Simples

5.2 Teste do JWT

5.3 Verificar Logs

Possíveis Problemas e Soluções

Problema: "Callback não é executado"

Problema: "JWT inválido"

Problema: "CORS error"

Problema: "Usuário não aparece como logado"

Checklist de Implementação

Backend

Admin Zendesk

Frontend

Teste

Artigos relacionados