Conector de Zendesk

Conecta tu instancia de Zendesk Support con Brevo a través de Tajo para unificar los datos de soporte al cliente, segmentar por tickets, puntuar la satisfacción y automatizar marketing activado por soporte.

Resumen

Funcionalidades

• Sincronización de usuarios - Sincroniza los usuarios finales y agentes de Zendesk con los contactos de Brevo
• Seguimiento de tickets - Sincroniza los datos de ticket para una segmentación de marketing consciente del soporte
• Mapeo de organizaciones - Asocia contactos con organizaciones para flujos B2B
• Puntuaciones de satisfacción - Sincroniza datos de CSAT y NPS como atributos de Brevo
• Eventos de tickets - Registra la creación, resolución y escalado de tickets como disparadores de automatización
• Integración con help center - Registra las visitas a artículos y el comportamiento de búsqueda
• Soporte multicanal - Sincroniza datos de email, chat, voz y canales de mensajería
• Campos personalizados - Asocia campos personalizados de tickets y usuarios de Zendesk con Brevo

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Zendesk Support (Team, Professional o Enterprise)
2. Acceso de administrador a tu instancia de Zendesk
3. Un token de API o una app OAuth configurada
4. Una cuenta de Brevo con acceso a la API
5. Una cuenta de Tajo

Autenticación

Autenticación con token de API

Usa la autenticación con email/token para una configuración rápida.

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

Genera un token de API desde Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

OAuth 2.0

Usa OAuth para integraciones multiinstancia con acceso delegado del usuario.

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

Scopes requeridos

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)

Configuración

Configuración 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

Asignación de campos

Asocia los campos de usuario de Zendesk con atributos de contacto de Brevo:

Asignación 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 de la API

API de ticketing

API de usuarios

API de organizaciones

API de valoraciones de satisfacción

Eventos

Eventos de tickets

Eventos de usuario

Eventos de satisfacción

Ejemplos de código

Inicializar el 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 usuarios y 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
// }

Gestionar webhooks de 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');
});

Límites de velocidad

Los límites de velocidad de Zendesk varían según el plan:

Límites adicionales:

• API de búsqueda: 6 peticiones/minuto para anónimas, 100/minuto para autenticadas
• Exportaciones incrementales: 10 peticiones/minuto
• API en lote: 100 registros por petición en lote
• Entrega de webhooks: Reintento automático con backoff exponencial

Resolución de problemas

Problemas habituales

Modo depuración

Habilita el registro detallado:

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

Probar la conexión

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

Buenas prácticas

1. Usa exportaciones incrementales - Usa la API incremental para la sincronización de datos a gran escala
2. Filtra solo usuarios finales - Excluye agentes y administradores de la sincronización de contactos de Brevo
3. Sincroniza los datos CSAT - Usa las puntuaciones de satisfacción para segmentar por salud del cliente
4. Mapea organizaciones - Aprovecha los datos de organización para campañas de marketing B2B
5. Implementa reintentos de webhook - Gestiona los fallos temporales con elegancia
6. Usa side-loading - Incluye registros relacionados en las respuestas de la API para reducir el número de peticiones

Seguridad

• Autenticación con token de API - Acceso basado en token ligado al email del administrador
• OAuth 2.0 - Acceso delegado basado en token con control de scopes
• Firma de webhooks - Verificación de firma HMAC para los payloads de webhook
• Cifrado TLS - Toda la comunicación con la API se cifra vía HTTPS
• Lista blanca de IP - Restringe el acceso a la API por rango de IP

Recursos relacionados

• Documentación de la API de Zendesk
• Guía de webhooks de Zendesk
• Conector de Intercom
• Skill de sincronización de clientes
• API de contactos de Brevo