Trình Kết Nối Zendesk

Kết nối Zendesk Support instance của bạn với Brevo qua Tajo để unified customer support data, ticket-based segmentation, satisfaction scoring và support-triggered marketing automation.

Tổng Quan

Tính Năng

• Đồng bộ user - Đồng bộ Zendesk end-users và agents với contacts Brevo
• Theo dõi ticket - Đồng bộ dữ liệu ticket để phân đoạn marketing dựa trên support
• Ánh xạ organization - Liên kết contacts với organizations cho B2B workflows
• Satisfaction scores - Đồng bộ dữ liệu CSAT và NPS sang thuộc tính Brevo
• Ticket events - Theo dõi ticket creation, resolution và escalation cho automation triggers
• Tích hợp help center - Theo dõi lượt xem bài viết và hành vi tìm kiếm
• Hỗ trợ đa kênh - Đồng bộ dữ liệu từ email, chat, voice và messaging channels
• Custom fields - Ánh xạ Zendesk custom ticket và user fields sang Brevo

Yêu Cầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

1. Tài khoản Zendesk Support (Team, Professional, hoặc Enterprise)
2. Quyền admin vào Zendesk instance của bạn
3. API token hoặc OAuth app được cấu hình
4. Tài khoản Brevo với quyền truy cập API
5. Tài khoản Tajo

Xác Thực

Xác Thực API Token

Dùng email/token authentication để thiết lập nhanh.

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

Tạo API token từ Zendesk Admin > Apps and Integrations > APIs > Zendesk API.

OAuth 2.0

Dùng OAuth cho multi-instance integrations với delegated user access.

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

Phạm Vi Cần Thiết

read          # Quyền đọc tất cả tài nguyên
write         # Quyền ghi tất cả tài nguyên
tickets:read  # Đọc tickets (chi tiết)
users:read    # Đọc users (chi tiết)
organizations:read  # Đọc organizations (chi tiết)

Cấu Hình

Thiết Lập Cơ Bản

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

    # Tùy chọn đồng bộ dữ liệu
    sync:
      users: true
      tickets: true
      organizations: true
      satisfaction_ratings: true

    # Gán danh sách Brevo
    lists:
      all_customers: 30
      active_tickets: 31
      satisfied_customers: 32

Ánh Xạ Trường

Ánh xạ trường user Zendesk sang thuộc tính liên hệ Brevo:

Ánh Xạ Custom Field

field_mapping:
  # Trường tiêu chuẩn
  email: email
  name: FULLNAME
  phone: SMS

  # Số liệu support
  open_tickets: OPEN_TICKETS
  total_tickets: TOTAL_TICKETS
  avg_satisfaction: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Trường organization
  organization.name: COMPANY_NAME
  organization.tags: COMPANY_TAGS

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

API Endpoints

Ticketing API

Users API

Organizations API

Satisfaction Ratings API

Sự Kiện

Sự Kiện Ticket

Sự Kiện User

Sự Kiện Satisfaction

Ví Dụ Code

Khởi Tạo Trình Kết Nối

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

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

// Kết nối Zendesk
await tajo.connectors.connect('zendesk', {
  subdomain: 'yourcompany',
  email: '[email protected]',
  apiToken: process.env.ZENDESK_API_TOKEN
});

Đồng Bộ Users Và Tickets

// Full sync users và dữ liệu ticket
await tajo.connectors.sync('zendesk', {
  type: 'full',
  resources: ['users', 'tickets', 'organizations'],
  since: '2023-01-01'
});

// Kiểm tra trạng thái sync
const status = await tajo.connectors.status('zendesk');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   usersSynced: 8400,
//   ticketsSynced: 34200,
//   organizationsSynced: 1200
// }

Xử Lý Zendesk Webhooks

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

  // Xác minh 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');
});

Giới Hạn Tốc Độ

Giới hạn tốc độ Zendesk thay đổi theo gói:

Giới hạn bổ sung:

• Search API: 6 yêu cầu/phút cho anonymous, 100/phút cho authenticated
• Incremental exports: 10 yêu cầu/phút
• Batch API: 100 bản ghi mỗi batch request
• Webhook delivery: Tự động retry với exponential backoff

Khắc Phục Sự Cố

Sự Cố Phổ Biến

Chế Độ Debug

Bật verbose logging:

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

Kiểm Tra Kết Nối

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

Thực Hành Tốt Nhất

1. Dùng incremental exports - Dùng Incremental API để đồng bộ dữ liệu quy mô lớn
2. Chỉ lọc end-users - Loại trừ agents và admins khỏi đồng bộ contact Brevo
3. Đồng bộ dữ liệu CSAT - Dùng satisfaction scores để phân đoạn customer health
4. Ánh xạ organizations - Tận dụng dữ liệu organization cho B2B marketing campaigns
5. Triển khai webhook retries - Xử lý temporary failures một cách tinh tế
6. Dùng side-loading - Bao gồm related records trong API responses để giảm số lượng request

Bảo Mật

• Xác Thực API Token - Truy cập dựa trên token gắn với admin email
• OAuth 2.0 - Truy cập delegated dựa trên token với kiểm soát phạm vi
• Webhook signing - Xác minh chữ ký HMAC cho webhook payloads
• Mã hóa TLS - Tất cả giao tiếp API được mã hóa qua HTTPS
• IP whitelisting - Hạn chế truy cập API theo dải IP

Tài Nguyên Liên Quan

• Tài Liệu API Zendesk
• Hướng Dẫn Webhooks Zendesk
• Trình Kết Nối Intercom
• Customer Sync Skill
• Brevo Contacts API