Conector Zendesk

Conecte sua instância do Zendesk Support ao Brevo via Tajo para obter dados de suporte ao cliente unificados, segmentação baseada em tickets, pontuação de satisfação e automação de marketing disparada por suporte.

Visão geral

Recursos

• Sincronização de usuários - Sincronize end-users e agentes do Zendesk com contatos do Brevo
• Rastreamento de tickets - Sincronize dados de tickets para segmentação de marketing consciente do suporte
• Mapeamento de organizações - Associe contatos com organizações para workflows B2B
• Pontuações de satisfação - Sincronize dados CSAT e NPS como atributos do Brevo
• Eventos de ticket - Rastreie criação, resolução e escalação de tickets para gatilhos de automação
• Integração com central de ajuda - Rastreie visualizações de artigos e comportamento de busca
• Suporte multicanal - Sincronize dados de canais de e-mail, chat, voz e mensageria
• Campos personalizados - Mapeie campos personalizados de tickets e usuários do Zendesk para o Brevo

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma conta Zendesk Support (Team, Professional ou Enterprise)
2. Acesso de admin à sua instância do Zendesk
3. Token de API ou app OAuth configurado
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo

Autenticação

Autenticação por token de API

Use autenticação por e-mail/token para configuração rápida.

curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -u {email}/token:{api_token} \
  -H "Content-Type: application/json"

Gere um token de API em Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

OAuth 2.0

Use OAuth para integrações multi-instância com acesso delegado de usuário.

# Authorization URL
https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=read%20write

Escopos necessários

read          # Read access to all resources
write         # Write access to all resources
tickets:read  # Read tickets (granular)
users:read    # Read users (granular)
organizations:read  # Read organizations (granular)

Configuração

Configuração básica

connectors:
  zendesk:
    enabled: true
    subdomain: "yourcompany"
    auth:
      email: "[email protected]"
      api_token: "${ZENDESK_API_TOKEN}"

    # Data sync options
    sync:
      users: true
      tickets: true
      organizations: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_customers: 30
      active_tickets: 31
      satisfied_customers: 32

Mapeamento de campos

Mapeie campos de usuário do Zendesk para atributos de contato do Brevo:

Mapeamento de campos personalizados

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Support metrics
  open_tickets: OPEN_TICKETS
  total_tickets: TOTAL_TICKETS
  avg_satisfaction: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Organization fields
  organization.name: COMPANY_NAME
  organization.tags: COMPANY_TAGS

  # Custom fields
  user_fields.customer_type: CUSTOMER_TYPE
  user_fields.account_tier: ACCOUNT_TIER

Endpoints da API

API de Ticketing

API de Usuários

API de Organizações

API de Avaliações de satisfação

Eventos

Eventos de ticket

Eventos de usuário

Eventos de satisfação

Exemplos de código

Inicializar o conector

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Zendesk
await tajo.connectors.connect('zendesk', {
  subdomain: 'yourcompany',
  email: '[email protected]',
  apiToken: process.env.ZENDESK_API_TOKEN
});

Sincronizar usuários e tickets

// Full sync of users and ticket data
await tajo.connectors.sync('zendesk', {
  type: 'full',
  resources: ['users', 'tickets', 'organizations'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('zendesk');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   usersSynced: 8400,
//   ticketsSynced: 34200,
//   organizationsSynced: 1200
// }

Tratar webhooks do Zendesk

app.post('/webhooks/zendesk', async (req, res) => {
  const signature = req.get('X-Zendesk-Webhook-Signature');

  // Verify webhook signature
  if (!verifyZendeskSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('zendesk', {
    type: req.body.type,
    ticketId: req.body.ticket_id,
    userId: req.body.user_id,
    payload: req.body
  });

  res.status(200).send('OK');
});

Limites de taxa

Os limites de taxa do Zendesk variam conforme o plano:

Limites adicionais:

• API de busca: 6 requisições/minuto para anônimo, 100/minuto para autenticado
• Exportações incrementais: 10 requisições/minuto
• API em lote: 100 registros por requisição em lote
• Entrega de webhook: Retry automático com backoff exponencial

Solução de problemas

Problemas comuns

Modo de depuração

Habilite logs detalhados:

connectors:
  zendesk:
    debug: true
    log_level: verbose
    log_webhooks: true

Testar conexão

tajo connectors test zendesk
# ✓ API connection successful
# ✓ Users readable
# ✓ Tickets readable
# ✓ Organizations readable
# ✓ Webhooks configured

Melhores práticas

1. Use exportações incrementais - Use a API incremental para sincronização de dados em larga escala
2. Filtre apenas end-users - Exclua agentes e admins da sincronização de contatos do Brevo
3. Sincronize dados CSAT - Use pontuações de satisfação para segmentação de saúde do cliente
4. Mapeie organizações - Aproveite dados de organização para campanhas de marketing B2B
5. Implemente retries de webhook - Trate falhas temporárias com elegância
6. Use side-loading - Inclua registros relacionados nas respostas da API para reduzir a contagem de requisições

Segurança

• Autenticação por token de API - Acesso baseado em token vinculado ao e-mail do admin
• OAuth 2.0 - Acesso delegado baseado em token com controles de escopo
• Assinatura de webhook - Verificação de assinatura HMAC para payloads de webhook
• Criptografia TLS - Toda comunicação com a API é criptografada via HTTPS
• Whitelisting de IP - Restrinja o acesso à API por faixa de IP

Recursos relacionados

• Documentação da API do Zendesk
• Guia de Webhooks do Zendesk
• Conector Intercom
• Skill de sincronização de clientes
• API de contatos do Brevo