Коннектор Zendesk

Подключите инстанс Zendesk Support к Brevo через Tajo для единых данных о поддержке клиентов, сегментации на основе тикетов, скоринга удовлетворённости и маркетинговой автоматизации на основе событий поддержки.

Обзор

Возможности

• Синхронизация пользователей, синхронизация конечных пользователей и агентов Zendesk с контактами Brevo
• Отслеживание тикетов, синхронизация данных тикетов для сегментации в маркетинге с учётом поддержки
• Маппинг организаций, привязка контактов к организациям для B2B-рабочих процессов
• Оценки удовлетворённости, синхронизация данных CSAT и NPS в атрибуты Brevo
• События тикетов, трекинг создания, закрытия и эскалации тикетов для триггеров автоматизации
• Интеграция с центром помощи, отслеживание просмотров статей и поискового поведения
• Многоканальная поддержка, синхронизация данных из email, чата, голоса и мессенджеров
• Пользовательские поля, маппинг пользовательских полей тикетов и пользователей Zendesk в Brevo

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Аккаунт Zendesk Support (Team, Professional или Enterprise)
2. Права администратора в инстансе Zendesk
3. Настроенный API-токен или OAuth-приложение
4. Аккаунт Brevo с доступом к API
5. Аккаунт Tajo

Аутентификация

Аутентификация по API Token

Используйте аутентификацию email/token для быстрой настройки.

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

Генерируйте API-токен в Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

OAuth 2.0

Используйте OAuth для интеграций с несколькими инстансами с делегированным доступом пользователей.

# URL авторизации
https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=read%20write

Необходимые scope

read          # Доступ на чтение всех ресурсов
write         # Доступ на запись всех ресурсов
tickets:read  # Чтение тикетов (детальный)
users:read    # Чтение пользователей (детальный)
organizations:read  # Чтение организаций (детальный)

Конфигурация

Базовая настройка

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

    # Параметры синхронизации данных
    sync:
      users: true
      tickets: true
      organizations: true
      satisfaction_ratings: true

    # Назначение листов Brevo
    lists:
      all_customers: 30
      active_tickets: 31
      satisfied_customers: 32

Сопоставление полей

Сопоставьте поля пользователей Zendesk с атрибутами контактов Brevo:

Сопоставление пользовательских полей

field_mapping:
  # Стандартные поля
  email: email
  name: FULLNAME
  phone: SMS

  # Метрики поддержки
  open_tickets: OPEN_TICKETS
  total_tickets: TOTAL_TICKETS
  avg_satisfaction: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Поля организации
  organization.name: COMPANY_NAME
  organization.tags: COMPANY_TAGS

  # Пользовательские поля
  user_fields.customer_type: CUSTOMER_TYPE
  user_fields.account_tier: ACCOUNT_TIER

Эндпоинты API

Ticketing API

Users API

Organizations API

Satisfaction Ratings API

События

События тикетов

События пользователей

События удовлетворённости

Примеры кода

Инициализация коннектора

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

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

// Подключение Zendesk
await tajo.connectors.connect('zendesk', {
  subdomain: 'yourcompany',
  email: '[email protected]',
  apiToken: process.env.ZENDESK_API_TOKEN
});

Синхронизация пользователей и тикетов

// Полная синхронизация пользователей и данных тикетов
await tajo.connectors.sync('zendesk', {
  type: 'full',
  resources: ['users', 'tickets', 'organizations'],
  since: '2023-01-01'
});

// Проверка статуса синхронизации
const status = await tajo.connectors.status('zendesk');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   usersSynced: 8400,
//   ticketsSynced: 34200,
//   organizationsSynced: 1200
// }

Обработка вебхуков Zendesk

app.post('/webhooks/zendesk', async (req, res) => {
  const signature = req.get('X-Zendesk-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');
});

Ограничения скорости

Лимиты скорости Zendesk варьируются в зависимости от плана:

Дополнительные ограничения:

• Search API: 6 запросов/мин для анонимных, 100/мин для авторизованных
• Инкрементальный экспорт: 10 запросов/мин
• Batch API: 100 записей на batch-запрос
• Доставка вебхуков: автоматические повторные попытки с экспоненциальной задержкой

Устранение неполадок

Частые проблемы

Режим отладки

Включение подробного логирования:

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

Проверка подключения

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

Лучшие практики

1. Используйте инкрементальный экспорт, применяйте Incremental API для крупномасштабной синхронизации данных
2. Фильтруйте только конечных пользователей, исключайте агентов и администраторов из синхронизации контактов Brevo
3. Синхронизируйте CSAT-данные, используйте оценки удовлетворённости для сегментации здоровья клиентов
4. Маппируйте организации, используйте данные организаций для B2B-маркетинговых кампаний
5. Реализуйте повторные попытки вебхуков, корректно обрабатывайте временные сбои
6. Используйте side-loading, включайте связанные записи в ответы API для уменьшения количества запросов

Безопасность

• Аутентификация по API Token, доступ на основе токена, привязанного к email администратора
• OAuth 2.0, делегированный доступ на основе токенов с контролем scope
• Подпись вебхуков, верификация HMAC-подписи для полезных нагрузок вебхуков
• TLS-шифрование, все API-коммуникации зашифрованы через HTTPS
• IP-разрешение, ограничение доступа к API по диапазону IP

Связанные ресурсы

• Документация Zendesk API
• Руководство Zendesk Webhooks
• Коннектор Intercom
• Скилл синхронизации клиентов
• Brevo Contacts API