Zendesk 连接器
通过 Tajo 将您的 Zendesk Support 实例连接到 Brevo，实现统一的客户支持数据、基于工单的细分、满意度评分以及支持触发的营销自动化。
概览
| 属性 | 值 |
|---|---|
| 平台 | Zendesk |
| 类别 | 支持 |
| 设置复杂度 | 中等 |
| 官方集成 | 是 |
| 同步数据 | 工单、用户、组织、事件 |
| API 基础 URL | https://{subdomain}.zendesk.com/api/v2 |
功能
- 用户同步 - 将 Zendesk 终端用户和客服与 Brevo 联系人同步
- 工单跟踪 - 同步工单数据，用于支持感知营销细分
- 组织映射 - 将联系人与组织关联，实现 B2B 工作流
- 满意度评分 - 将 CSAT 和 NPS 数据同步到 Brevo 属性
- 工单事件 - 跟踪工单创建、解决和升级，用于自动化触发
- 帮助中心集成 - 跟踪文章浏览和搜索行为
- 多渠道支持 - 同步来自邮件、聊天、语音和消息渠道的数据
- 自定义字段 - 将 Zendesk 自定义工单和用户字段映射到 Brevo
前提条件
开始之前，请确保您已具备：
- Zendesk Support 账户（Team、Professional 或 Enterprise 版本）
- 对 Zendesk 实例的管理员访问权限
- 已配置 API 令牌或 OAuth 应用
- 具有 API 访问权限的 Brevo 账户
- Tajo 账户
认证
API 令牌认证
使用邮箱/令牌认证快速设置。
curl https://{subdomain}.zendesk.com/api/v2/users.json \ -u {email}/token:{api_token} \ -H "Content-Type: application/json"从 Zendesk 管理 > 应用和集成 > API > Zendesk API 生成 API 令牌。
OAuth 2.0
用于具有委托用户访问权限的多实例集成。
# Authorization URLhttps://{subdomain}.zendesk.com/oauth/authorizations/new? response_type=code& client_id={client_id}& redirect_uri={redirect_uri}& scope=read%20write所需范围
read # Read access to all resourceswrite # Write access to all resourcestickets:read # Read tickets (granular)users:read # Read users (granular)organizations:read # Read organizations (granular)配置
基础设置
connectors: zendesk: enabled: true subdomain: "yourcompany" auth: 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字段映射
将 Zendesk 用户字段映射到 Brevo 联系人属性：
默认映射
| Parameter | Type | Description |
|---|---|---|
email required | string | 用户邮箱地址（唯一标识符） |
name optional | string | 全名，拆分为 FIRSTNAME/LASTNAME |
phone optional | string | 映射到 SMS 属性，用于 WhatsApp/短信 |
organization_id optional | integer | 用于 B2B 映射的关联组织 |
role optional | string | 用户角色（终端用户、客服、管理员） |
tags optional | array | 来自 Zendesk 的用户标签 |
ticket_restriction optional | string | 工单访问级别 |
custom_fields optional | object | 自定义用户字段值 |
自定义字段映射
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_TIERAPI 端点
工单 API
| 方法 | 端点 | 描述 |
|---|---|---|
GET | /api/v2/tickets | 列出工单 |
POST | /api/v2/tickets | 创建工单 |
PUT | /api/v2/tickets/{id} | 更新工单 |
GET | /api/v2/tickets/{id} | 显示工单 |
GET | /api/v2/search.json?query={query} | 搜索工单 |
用户 API
| 方法 | 端点 | 描述 |
|---|---|---|
GET | /api/v2/users | 列出用户 |
POST | /api/v2/users | 创建用户 |
PUT | /api/v2/users/{id} | 更新用户 |
GET | /api/v2/users/{id} | 显示用户 |
GET | /api/v2/users/search.json?query={query} | 搜索用户 |
组织 API
| 方法 | 端点 | 描述 |
|---|---|---|
GET | /api/v2/organizations | 列出组织 |
POST | /api/v2/organizations | 创建组织 |
GET | /api/v2/organizations/{id}/users | 列出组织成员 |
满意度评分 API
| 方法 | 端点 | 描述 |
|---|---|---|
GET | /api/v2/satisfaction_ratings | 列出满意度评分 |
GET | /api/v2/satisfaction_ratings/{id} | 显示评分 |
事件
工单事件
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
ticket.created | 新工单提交 | 支持确认 |
ticket.updated | 工单状态变更 | 状态通知 |
ticket.solved | 工单标记为已解决 | CSAT 调查触发 |
ticket.reopened | 已解决工单重新打开 | 升级提醒 |
用户事件
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
user.created | 新用户注册 | 欢迎到支持中心 |
user.updated | 用户档案变更 | 属性同步 |
user.merged | 用户合并 | 去重 |
满意度事件
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
satisfaction_rating.created | CSAT 已提交 | 反馈处理 |
satisfaction_rating.bad | 负面评分 | 挽回外联 |
satisfaction_rating.good | 正面评分 | 倡导活动 |
代码示例
初始化连接器
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect Zendeskawait tajo.connectors.connect('zendesk', { subdomain: 'yourcompany', apiToken: process.env.ZENDESK_API_TOKEN});同步用户和工单
// Full sync of users and ticket dataawait tajo.connectors.sync('zendesk', { type: 'full', resources: ['users', 'tickets', 'organizations'], since: '2023-01-01'});
// Check sync statusconst status = await tajo.connectors.status('zendesk');console.log(status);// {// connected: true,// lastSync: '2024-01-15T10:30:00Z',// usersSynced: 8400,// ticketsSynced: 34200,// organizationsSynced: 1200// }处理 Zendesk Webhook
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');});速率限制
Zendesk 速率限制因计划而异：
| 计划 | 速率限制 | 详情 |
|---|---|---|
| Team | 200 请求/分钟 | 每个 API 令牌 |
| Professional | 400 请求/分钟 | 每个 API 令牌 |
| Enterprise | 700 请求/分钟 | 每个 API 令牌 |
| 高容量附加组件 | 2,500 请求/分钟 | 每个 API 令牌 |
附加限制：
- 搜索 API：匿名 6 请求/分钟，已认证 100 请求/分钟
- 增量导出：10 请求/分钟
- 批量 API：每次批量请求 100 条记录
- Webhook 投递：带指数退避的自动重试
速率限制响应头
监控 X-Rate-Limit-Remaining 和 Retry-After 请求头以管理您的 API 使用情况。
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 401 Unauthorized | API 令牌无效 | 在 Zendesk 管理中重新生成令牌 |
| 403 Forbidden | 权限不足 | 检查客服或管理员角色要求 |
| 用户未同步 | 用户是客服，而非终端用户 | 在同步配置中按角色筛选 |
| 未收到 Webhook | 触发器/目标未配置 | 在 Zendesk 管理中设置 Webhook 目标 |
| 搜索返回空 | 索引延迟 | 等待 1-2 分钟让搜索索引更新 |
调试模式
启用详细日志记录：
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最佳实践
- 使用增量导出 - 使用增量 API 进行大规模数据同步
- 仅筛选终端用户 - 从 Brevo 联系人同步中排除客服和管理员
- 同步 CSAT 数据 - 使用满意度评分进行客户健康度细分
- 映射组织 - 利用组织数据进行 B2B 营销活动
- 实施 Webhook 重试 - 优雅地处理临时故障
- 使用侧加载 - 在 API 响应中包含相关记录，减少请求次数
安全
- API 令牌认证 - 与管理员邮箱绑定的基于令牌的访问
- OAuth 2.0 - 带范围控制的基于令牌的委托访问
- Webhook 签名 - HMAC 签名验证 Webhook 负载
- TLS 加密 - 所有 API 通信通过 HTTPS 加密
- IP 白名单 - 按 IP 范围限制 API 访问