Pular para conteúdo

🎫 Zendesk Integration - Lumina Flow Builder

Visão Geral

A integração Zendesk permite conectar seus flows do WhatsApp com a plataforma de suporte Zendesk, automatizando criação de tickets, gestão de usuários e organizações diretamente de conversas no WhatsApp.

O que é Zendesk?

Zendesk é uma plataforma completa de atendimento ao cliente que oferece:

  • 🎫 Gestão de Tickets: Sistema centralizado para rastreamento de solicitações
  • 👥 Gestão de Usuários: Cadastro e organização de clientes
  • 🏢 Organizações: Agrupamento de usuários por empresa
  • 📊 Relatórios: Análise de desempenho e SLA
  • 🔄 Automações: Workflows e regras de negócio

Por que usar Zendesk no Lumina?

Integrar Zendesk com WhatsApp permite:

  1. Suporte Automatizado 24/7: Clientes abrem tickets via WhatsApp automaticamente
  2. Rastreamento Centralizado: Todas as solicitações registradas em um único sistema
  3. Histórico Completo: Manter registro de todas as interações com clientes
  4. SLA e Priorização: Gerenciar urgências e prazos de atendimento
  5. Equipe Unificada: Time de suporte trabalha em interface conhecida (Zendesk)

Recursos Disponíveis

A integração Zendesk oferece 3 recursos principais com 16 operações no total:

🎫 Tickets (5 operações)

Gerenciamento completo de tickets de suporte:

👥 Users (6 operações)

Gestão de usuários (clientes, agentes, admins):

🏢 Organizations (5 operações)

Gestão de organizações/empresas:

Configuração Inicial

1. Obter Credenciais do Zendesk

Para usar a integração, você precisa:

  1. Subdomain: Seu subdomínio Zendesk (ex: "empresa" se sua URL é empresa.zendesk.com)
  2. Email Admin: Email de uma conta com permissões de administrador
  3. API Token: Token de API gerado nas configurações do Zendesk

2. Gerar API Token no Zendesk

  1. Acesse: Admin → Channels → API
  2. Ative Token Access
  3. Clique em Add API token
  4. Copie o token gerado (será mostrado apenas uma vez!)
  5. Guarde o token em local seguro

3. Configurar no Lumina Flow

Todas as operações Zendesk requerem objeto config:

{
  "config": {
    "subdomain": "sua-empresa",
    "email": "admin@empresa.com",
    "apiToken": "seu_token_aqui_abc123xyz"
  }
}

Casos de Uso Comuns

🎯 Caso 1: Suporte Automatizado Completo

Objetivo: Cliente reporta problema via WhatsApp → Sistema cria usuário (se não existir) + cria ticket

Flow: 1. Cliente inicia conversa 2. Sistema busca se usuário já existe (USER SEARCH) 3. Se não existir → cria usuário (USER CREATE) 4. Coleta detalhes do problema (INPUT) 5. Cria ticket no Zendesk (TICKET CREATE) 6. Confirma número do ticket para o cliente

Benefício: Zero intervenção manual - tudo automatizado

🎯 Caso 2: Consulta de Status de Ticket

Objetivo: Cliente pergunta andamento do ticket

Flow: 1. Cliente envia mensagem com número do ticket 2. Sistema busca ticket (TICKET GET) 3. Verifica status atual 4. Informa cliente de forma amigável

Benefício: Cliente acompanha sozinho sem precisar ligar

🎯 Caso 3: Resolução Confirmada pelo Cliente

Objetivo: Cliente confirma que problema foi resolvido

Flow: 1. Sistema pergunta se problema foi resolvido 2. Cliente confirma (sim/não) 3. Se sim → atualiza ticket para "solved" (TICKET UPDATE) 4. Se não → aumenta prioridade e notifica equipe

Benefício: Fechamento automático de tickets resolvidos

🎯 Caso 4: Escalação Automática por Tempo

Objetivo: Tickets antigos são automaticamente priorizados

Flow: 1. Schedule executa diariamente 2. Busca todos os tickets (TICKET GETALL) 3. Filtra tickets abertos há mais de 24h 4. Aumenta prioridade automaticamente (TICKET UPDATE) 5. Adiciona comentário explicando escalação

Benefício: SLA mantido automaticamente

🎯 Caso 5: Conformidade LGPD

Objetivo: Cliente solicita remoção de dados

Flow: 1. Cliente solicita deleção (LGPD) 2. Sistema busca usuário por email (USER SEARCH) 3. Busca todos os tickets do usuário (TICKET GETALL + filtro) 4. Deleta todos os tickets (TICKET DELETE em loop) 5. Deleta o usuário (USER DELETE) 6. Confirma deleção para o cliente

Benefício: Conformidade automática com LGPD/GDPR

Exemplos de Flows Completos

Exemplo 1: Criar Ticket Básico

{
  "name": "Criar Ticket Simples",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Descrever Problema",
        "parameters": {
          "message": "Descreva seu problema:",
          "variable": "problema"
        }
      }
    },
    {
      "id": "zendesk_1",
      "type": "zendesk",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Criar Ticket",
        "resource": "ticket",
        "operation": "create",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "subject": "Suporte WhatsApp - {{user_name}}",
        "description": "{{problema}}",
        "priority": "normal",
        "status": "new",
        "type": "problem",
        "responseVariable": "ticket"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Ticket #{{ticket.id}} criado!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "zendesk_1" },
    { "source": "zendesk_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo 2: Buscar ou Criar Usuário

{
  "name": "Buscar ou Criar Usuário",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Digite seu email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "zendesk_search",
      "type": "zendesk",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Buscar",
        "resource": "user",
        "operation": "search",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "query": "{{email}}",
        "responseVariable": "busca"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 550, "y": 50 },
      "data": {
        "label": "Existe?",
        "parameters": {
          "conditions": [
            {
              "variable": "busca.count",
              "operator": "greater_than",
              "value": "0"
            }
          ]
        }
      }
    },
    {
      "id": "message_found",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Encontrado",
        "parameters": {
          "message": "Bem-vindo de volta!"
        }
      }
    },
    {
      "id": "zendesk_create",
      "type": "zendesk",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Criar",
        "resource": "user",
        "operation": "create",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "name": "{{user_name}}",
        "email": "{{email}}",
        "role": "end-user",
        "responseVariable": "usuario"
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 850, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "zendesk_search" },
    { "source": "zendesk_search", "target": "condition_1" },
    { "source": "condition_1", "target": "message_found", "label": "true" },
    { "source": "condition_1", "target": "zendesk_create", "label": "false" },
    { "source": "message_found", "target": "end_1" },
    { "source": "zendesk_create", "target": "end_1" }
  ]
}

Boas Práticas Gerais

✅ Faça

  1. Sempre use USER SEARCH antes de USER CREATE para evitar duplicatas
  2. Armazene IDs em variáveis (ticket_id, user_id) para uso posterior
  3. Adicione contexto nos comentários (canal: WhatsApp, telefone, horário)
  4. Use prioridades de forma inteligente - não abuse de "urgent"
  5. Implemente confirmação para DELETE - operação irreversível
  6. Trate erros - use CONDITION para verificar se operações foram bem-sucedidas
  7. Use variáveis dinâmicas nos subject/description ({{user_name}}, {{user_phone}})

❌ Não Faça

  1. Não exponha API tokens em logs ou mensagens ao cliente
  2. Não crie tickets duplicados - sempre verifique antes
  3. Não delete dados sem confirmação - especialmente tickets reais
  4. Não ignore rate limits - adicione DELAY entre operações em massa
  5. Não assuma que operações sempre funcionam - trate erros
  6. Não use status "closed" ao criar tickets - use "new"
  7. Não faça múltiplas chamadas quando pode fazer uma - agrupe updates

Campos Comuns

Status de Ticket

  • new - Ticket recém-criado, não atribuído
  • open - Em atendimento
  • pending - Aguardando resposta do cliente
  • hold - Em espera
  • solved - Problema resolvido
  • closed - Ticket fechado permanentemente

Prioridades

  • low - Baixa prioridade
  • normal - Prioridade padrão
  • high - Alta prioridade
  • urgent - Urgente - requer atenção imediata

Tipos de Ticket

  • problem - Problema técnico
  • incident - Incidente relacionado a outro problema
  • question - Dúvida/pergunta
  • task - Tarefa/solicitação

Roles de Usuário

  • end-user - Cliente final (padrão)
  • agent - Agente de suporte
  • admin - Administrador

Troubleshooting

Erro: "Subdomain not found"

Causa: Subdomain incorreto no config

Solução: Verifique se o subdomain está correto (ex: se sua URL é empresa.zendesk.com, use "subdomain": "empresa")

Erro: "Authentication failed"

Causa: Email ou API token incorretos

Solução: 1. Verifique se o email tem permissões de admin 2. Gere novo API token no Zendesk 3. Confirme que está usando o formato correto: email/token:api_token

Erro: "Record not found" (404)

Causa: Ticket/User/Organization ID não existe

Solução: Use SEARCH ou GET antes para verificar existência

Erro: "Email already exists"

Causa: Tentando criar usuário com email já cadastrado

Solução: Use USER SEARCH antes de CREATE para verificar duplicata

Erro: "Rate limit exceeded"

Causa: Muitas requisições em pouco tempo

Solução: Adicione DELAY entre operações em loops

Performance e Limites

Limites da API Zendesk

  • Rate Limit: 700 requisições por minuto
  • Paginação: Máximo 100 registros por página (getAll)
  • Timeout: Requisições > 30s podem falhar

Otimizações

  1. Cache de Dados: Armazene resultados em variáveis para reutilizar
  2. Batch Operations: Agrupe múltiplas atualizações em uma chamada
  3. Filtros Locais: Use CALCULATOR para filtrar após GETALL ao invés de múltiplos GETs
  4. Delays Inteligentes: Adicione DELAY em loops para respeitar rate limits

Segurança

Proteção de Credenciais

  1. Nunca exponha tokens em mensagens ao cliente
  2. Use variáveis de ambiente para armazenar credenciais (se possível)
  3. Rotacione tokens periodicamente
  4. Limite permissões do usuário API ao mínimo necessário

Conformidade LGPD/GDPR

A integração oferece operações DELETE para conformidade com:

  • Direito ao Esquecimento: USER DELETE + TICKET DELETE
  • Portabilidade: GET/GETALL para exportar dados
  • Correção: UPDATE para corrigir dados incorretos

Suporte e Recursos

Documentação Oficial Zendesk

Documentação Lumina

Total de Operações Documentadas: 16

Última Atualização: 2025-01-15

Status: ✅ Documentação Completa