On this page

Intercom 连接器

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

概览

属性值
平台Intercom
类别支持
设置复杂度中等
官方集成是
同步数据联系人、对话、公司、事件
API 基础 URLhttps://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. 复制访问令牌
Terminal window
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 数据的集成。

Terminal window
# 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 更新日志了解重大变更。

配置

基础设置 

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

自定义属性键值对

自定义属性映射 

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退订邮件偏好更新

代码示例

初始化连接器 

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

同步联系人和对话 

// 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 

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 根据您的计划应用速率限制：

计划速率限制详情
Starter20 请求/10 秒每应用
Pro50 请求/10 秒每应用
Premium100 请求/10 秒每应用
搜索端点1 请求/秒每应用
滚动端点1 请求/分钟每应用

附加限制：

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

速率限制响应

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

故障排除

常见问题

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

调试模式

启用详细日志记录：

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

测试连接

Terminal window
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 加密
  • 数据访问控制 - 每个应用配置的细粒度数据访问

相关资源

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 助手

你好！关于文档有任何问题都可以问我。