---
title: "Intercom 连接器"
description: "完整的 Intercom 集成指南，通过 Tajo 将联系人、对话、公司和参与事件与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/support/intercom/
markdown: https://tajo.io/zh-cn/docs/connectors/support/intercom.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Intercom 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 Tajo 将您的 Intercom 工作区连接到 Brevo，实现统一的客户消息传递、对话跟踪以及由支持和产品数据驱动的参与营销自动化。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Intercom |
| **类别** | 支持 |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 联系人、对话、公司、事件 |
| **API 基础 URL** | `https://api.intercom.io` |

## 功能

- **联系人同步** - Intercom 用户和线索与 Brevo 联系人的双向同步
- **对话跟踪** - 同步对话数据，用于支持驱动的细分
- **公司映射** - 将联系人与公司关联，实现基于账户的工作流
- **自定义属性** - 将 Intercom 自定义属性映射到 Brevo 联系人字段
- **事件跟踪** - 同步自定义事件和用户活动，用于行为定向
- **标签同步** - 将 Intercom 标签映射到 Brevo 列表会员资格或属性
- **Messenger 数据** - 跟踪应用内消息参与和聊天互动
- **AI 客服集成** - 将 AI 客服对话结果与 Brevo 同步

## 前提条件

开始之前，请确保您已具备：

1. Intercom 工作区（Starter、Pro 或 Premium 计划）
2. 具有访问令牌的 Intercom 应用（私有应用）或已配置 OAuth（公共应用）
3. 具有 API 访问权限的 Brevo 账户
4. Tajo 账户

## 认证

### 访问令牌（私有应用）

用于访问您自己工作区数据的私有集成。

1. 前往开发者中心 > 您的应用 > 创建新应用
2. 与您的 Intercom 工作区关联
3. 复制访问令牌

```bash
curl https://api.intercom.io/contacts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Intercom-Version: 2.11"
```

### OAuth 2.0（公共应用）

用于访问其他客户 Intercom 数据的集成。

```bash
# Authorization URL
https://app.intercom.com/oauth?client_id={client_id}&state={state}

# Token exchange
curl -X POST https://api.intercom.io/auth/eagle/token \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"
```

API 版本控制

请始终在请求中包含 `Intercom-Version` 请求头。Tajo 默认使用 API 版本 2.11。请查看 Intercom 更新日志了解重大变更。

## 配置

### 基础设置

```yaml
connectors:
  intercom:
    enabled: true
    access_token: "${INTERCOM_ACCESS_TOKEN}"
    api_version: "2.11"

    # Data sync options
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Sync direction
    direction: intercom_to_brevo

    # Brevo list assignment
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37
```

### 字段映射

将 Intercom 联系人数据映射到 Brevo 联系人属性：

#### 默认映射

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | 联系人邮箱地址（唯一标识符） |
| `name` optional | string | 全名，拆分为 FIRSTNAME/LASTNAME |
| `phone` optional | string | 映射到 SMS 属性，用于 WhatsApp/短信 |
| `role` optional | string | 联系人类型：user 或 lead |
| `company.name` optional | string | 关联的公司名称 |
| `signed_up_at` optional | timestamp | 用户注册日期 |
| `last_seen_at` optional | timestamp | 最后活跃时间戳 |
| `custom_attributes` optional | object | 自定义属性键值对 |

#### 自定义属性映射

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

  # Engagement fields
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Company fields
  company.name: COMPANY_NAME
  company.plan: COMPANY_PLAN
  company.size: COMPANY_SIZE

  # Custom attributes
  custom_attributes.plan_tier: PLAN_TIER
  custom_attributes.feature_usage: FEATURE_USAGE
```

## API 端点

### 联系人 API

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/contacts` | 列出所有联系人 |
| `POST` | `/contacts` | 创建联系人 |
| `PUT` | `/contacts/{id}` | 更新联系人 |
| `GET` | `/contacts/{id}` | 检索联系人 |
| `POST` | `/contacts/search` | 搜索联系人 |
| `DELETE` | `/contacts/{id}` | 归档联系人 |

### 对话 API

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/conversations` | 列出对话 |
| `GET` | `/conversations/{id}` | 检索对话 |
| `POST` | `/conversations` | 创建对话 |
| `POST` | `/conversations/{id}/reply` | 回复对话 |
| `POST` | `/conversations/{id}/parts` | 添加对话片段 |

### 公司 API

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/companies` | 列出公司 |
| `POST` | `/companies` | 创建或更新公司 |
| `GET` | `/companies/{id}` | 检索公司 |
| `GET` | `/companies/{id}/contacts` | 列出公司联系人 |

### 事件 API

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `POST` | `/events` | 提交事件 |
| `GET` | `/events?type=user&intercom_user_id={id}` | 列出用户事件 |

## 事件

### 对话事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `conversation.created` | 新对话开始 | 支持工单提醒 |
| `conversation.closed` | 对话已解决 | CSAT 调查触发 |
| `conversation.rating.added` | 提交评分 | 满意度跟踪 |
| `conversation.snoozed` | 对话已暂停 | 跟进调度 |

### 联系人事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `contact.created` | 新联系人添加 | 欢迎序列 |
| `contact.updated` | 联系人数据变更 | 属性同步 |
| `contact.deleted` | 联系人归档 | 清理 |
| `contact.tag.created` | 标签添加到联系人 | 细分更新 |

### 用户事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `user.created` | 新用户注册 | 引导流程 |
| `user.email.updated` | 邮箱变更 | 联系人合并 |
| `user.unsubscribed` | 退订邮件 | 偏好更新 |

## 代码示例

### 初始化连接器

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

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

// Connect Intercom
await tajo.connectors.connect('intercom', {
  accessToken: process.env.INTERCOM_ACCESS_TOKEN,
  apiVersion: '2.11'
});
```

### 同步联系人和对话

```javascript
// Full sync of contacts and conversation data
await tajo.connectors.sync('intercom', {
  type: 'full',
  resources: ['contacts', 'conversations', 'companies'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('intercom');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 14200,
//   conversationsSynced: 28400,
//   companiesSynced: 2100
// }
```

### 处理 Intercom Webhook

```javascript
import crypto from 'crypto';

app.post('/webhooks/intercom', async (req, res) => {
  const signature = req.get('X-Hub-Signature');
  const expectedSig = 'sha1=' + crypto
    .createHmac('sha1', process.env.INTERCOM_CLIENT_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('intercom', {
    topic: req.body.topic,
    data: req.body.data
  });

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

## 速率限制

Intercom 根据您的计划应用速率限制：

| 计划 | 速率限制 | 详情 |
| --- | --- | --- |
| Starter | 20 请求/10 秒 | 每应用 |
| Pro | 50 请求/10 秒 | 每应用 |
| Premium | 100 请求/10 秒 | 每应用 |
| 搜索端点 | 1 请求/秒 | 每应用 |
| 滚动端点 | 1 请求/分钟 | 每应用 |

附加限制：

- **批量操作**：每次批量请求 15 个联系人
- **事件提交**：每工作区 500 个事件/秒
- **Webhook 投递**：自动重试 24 小时
- **数据导出**：1 个并发导出

速率限制响应

Intercom 返回带有 `Retry-After` 请求头的 `429 Too Many Requests`。实施指数退避并遵守重试窗口。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | 令牌无效或已过期 | 在开发者中心重新生成访问令牌 |
| 联系人未同步 | 缺少邮箱字段 | Intercom 线索可能缺少邮箱；按角色筛选 |
| 对话数据为空 | 应用缺少对话范围 | 重新授权，添加对话读取权限 |
| 未收到 Webhook | Webhook 未注册 | 在开发者中心设置中配置 Webhook |
| API 版本不匹配 | 新版本中有重大变更 | 使用 `Intercom-Version` 请求头固定 API 版本 |

### 调试模式

启用详细日志记录：

```yaml
connectors:
  intercom:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### 测试连接

```bash
tajo connectors test intercom
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Conversations readable
# ✓ Companies readable
# ✓ Webhooks registered
```

## 最佳实践

1. **固定 API 版本** - 始终指定 `Intercom-Version` 以避免重大变更
2. **高效使用搜索 API** - 使用筛选器和分页减少数据传输
3. **同步用户和线索** - 在 Brevo 中捕获完整漏斗
4. **映射对话标签** - 使用对话标签进行支持后营销细分
5. **跟踪自定义事件** - 向 Intercom 提交关键产品事件，用于行为定向
6. **处理联系人合并** - 为重复联系人实现合并逻辑

## 安全

- **访问令牌** - 私有应用的 Bearer 令牌认证
- **OAuth 2.0** - 公共应用的带客户端密钥的委托授权
- **Webhook 验证** - 通过 `X-Hub-Signature` 进行 HMAC SHA-1 签名验证
- **TLS 加密** - 所有 API 通信通过 HTTPS 加密
- **数据访问控制** - 每个应用配置的细粒度数据访问

## 相关资源

- [Intercom 开发者文档](https://developers.intercom.com/docs)
- [Intercom API 参考](https://developers.intercom.com/docs/references/introduction)
- [Zendesk 连接器](https://tajo.io/zh-cn/docs/connectors/support/zendesk)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)