intercom-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intercom Automation via Rube MCP

通过Rube MCP实现Intercom自动化

Automate Intercom operations through Composio's Intercom toolkit via Rube MCP.

通过Composio的Intercom工具包，借助Rube MCP自动化Intercom操作。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Intercom connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
intercom
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需具备RUBE_SEARCH_TOOLS权限）
通过
```
RUBE_MANAGE_CONNECTIONS
```
激活Intercom连接，工具包选择
```
intercom
```
请始终先调用
```
RUBE_SEARCH_TOOLS
```
获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
intercom
```
If connection is not ACTIVE, follow the returned auth link to complete Intercom OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥——只需添加端点即可使用。

通过确认
```
RUBE_SEARCH_TOOLS
```
能正常响应，验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包为
```
intercom
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Intercom OAuth认证
在运行任何工作流之前，确认连接状态为ACTIVE

Core Workflows

核心工作流

1. Manage Conversations

1. 对话管理

When to use: User wants to create, list, search, or manage support conversations

Tool sequence:

```
INTERCOM_LIST_ALL_ADMINS
```
- Get admin IDs for assignment [Prerequisite]
```
INTERCOM_LIST_CONVERSATIONS
```
- List all conversations [Optional]
```
INTERCOM_SEARCH_CONVERSATIONS
```
- Search with filters [Optional]
```
INTERCOM_GET_CONVERSATION
```
- Get conversation details [Optional]
```
INTERCOM_CREATE_CONVERSATION
```
- Create a new conversation [Optional]

Key parameters:

```
from
```
: Object with
```
type
```
('user'/'lead') and
```
id
```
for conversation creator
```
body
```
: Message body (HTML supported)
```
id
```
: Conversation ID for retrieval
```
query
```
: Search query object with
```
field
```
,
```
operator
```
,
```
value
```

Pitfalls:

CREATE_CONVERSATION requires a contact (user/lead) as the
```
from
```
field, not an admin
Conversation bodies support HTML; plain text is auto-wrapped in
```
<p>
```
tags
Search query uses structured filter objects, not free-text search
Conversation IDs are numeric strings

适用场景：用户需要创建、列出、搜索或管理支持对话时

工具调用流程:

```
INTERCOM_LIST_ALL_ADMINS
```
- 获取用于分配任务的管理员ID [前提步骤]
```
INTERCOM_LIST_CONVERSATIONS
```
- 列出所有对话 [可选]
```
INTERCOM_SEARCH_CONVERSATIONS
```
- 使用筛选条件搜索对话 [可选]
```
INTERCOM_GET_CONVERSATION
```
- 获取对话详情 [可选]
```
INTERCOM_CREATE_CONVERSATION
```
- 创建新对话 [可选]

关键参数:

```
from
```
: 包含
```
type
```
（'user'/'lead'）和
```
id
```
的对象，代表对话发起者
```
body
```
: 消息内容（支持HTML格式）
```
id
```
: 用于检索的对话ID
```
query
```
: 包含
```
field
```
、
```
operator
```
、
```
value
```
的搜索查询对象

注意事项:

CREATE_CONVERSATION要求
```
from
```
字段为联系人（用户/潜在客户），而非管理员
对话内容支持HTML格式；纯文本会自动被
```
<p>
```
标签包裹
搜索查询使用结构化筛选对象，而非自由文本搜索
对话ID为数字字符串

2. Reply and Manage Conversation State

2. 回复与对话状态管理

When to use: User wants to reply to, close, reopen, or assign conversations

Tool sequence:

```
INTERCOM_GET_CONVERSATION
```
- Get current state [Prerequisite]
```
INTERCOM_REPLY_TO_CONVERSATION
```
- Add a reply [Optional]
```
INTERCOM_ASSIGN_CONVERSATION
```
- Assign to admin/team [Optional]
```
INTERCOM_CLOSE_CONVERSATION
```
- Close conversation [Optional]
```
INTERCOM_REOPEN_CONVERSATION
```
- Reopen closed conversation [Optional]

Key parameters:

```
conversation_id
```
/
```
id
```
: Conversation ID
```
body
```
: Reply message body (HTML supported)
```
type
```
: Reply type ('admin' or 'user')
```
admin_id
```
: Admin ID for replies from admin, assignment, and close/reopen
```
assignee_id
```
: Admin or team ID for assignment
```
message_type
```
: 'comment' (default) or 'note' (internal)

Pitfalls:

```
admin_id
```
is REQUIRED for admin replies, close, reopen, and assignment operations
Always fetch admin IDs first with LIST_ALL_ADMINS or IDENTIFY_AN_ADMIN
Duplicate sends can occur on retry; implement idempotency checks
Internal notes use
```
message_type: 'note'
```
; visible only to workspace members
Closing requires an admin_id and optional body message

适用场景：用户需要回复、关闭、重新打开或分配对话时

工具调用流程:

```
INTERCOM_GET_CONVERSATION
```
- 获取对话当前状态 [前提步骤]
```
INTERCOM_REPLY_TO_CONVERSATION
```
- 添加回复内容 [可选]
```
INTERCOM_ASSIGN_CONVERSATION
```
- 将对话分配给管理员/团队 [可选]
```
INTERCOM_CLOSE_CONVERSATION
```
- 关闭对话 [可选]
```
INTERCOM_REOPEN_CONVERSATION
```
- 重新打开已关闭对话 [可选]

关键参数:

```
conversation_id
```
/
```
id
```
: 对话ID
```
body
```
: 回复消息内容（支持HTML格式）
```
type
```
: 回复类型（'admin' 或 'user'）
```
admin_id
```
: 管理员ID，用于管理员回复、分配、关闭/重新打开对话操作
```
assignee_id
```
: 用于分配的管理员或团队ID
```
message_type
```
: 'comment'（默认）或 'note'（内部备注）

注意事项:

管理员回复、关闭、重新打开和分配操作必须提供
```
admin_id
```
请始终先通过LIST_ALL_ADMINS或IDENTIFY_AN_ADMIN获取管理员ID
重试时可能会出现重复发送的情况，需实现幂等性检查
内部备注使用
```
message_type: 'note'
```
；仅工作区成员可见
关闭对话需要提供admin_id，可选附带消息内容

3. Manage Contacts

3. 联系人管理

When to use: User wants to search, view, or manage contacts (users and leads)

Tool sequence:

```
INTERCOM_SEARCH_CONTACTS
```
- Search contacts with filters [Required]
```
INTERCOM_GET_A_CONTACT
```
- Get specific contact [Optional]
```
INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID
```
- Look up by external ID [Optional]
```
INTERCOM_LIST_CONTACTS
```
- List all contacts [Optional]

INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT

- Get contact tags [Optional]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT

- Get contact segments [Optional]

```
INTERCOM_DETACH_A_CONTACT
```
- Remove contact from company [Optional]

Key parameters:

```
contact_id
```
: Contact ID for retrieval
```
external_id
```
: External system ID for lookup
```
query
```
: Search filter object with
```
field
```
,
```
operator
```
,
```
value
```
```
pagination
```
: Object with
```
per_page
```
and
```
starting_after
```
cursor

Pitfalls:

SEARCH_CONTACTS uses structured query filters, not free-text; format:
```
{field, operator, value}
```
Supported operators:
```
=
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
~
```
(contains),
```
!~
```
(not contains),
```
IN
```
,
```
NIN
```
Contact types are 'user' (identified) or 'lead' (anonymous)
LIST_CONTACTS returns paginated results; use
```
starting_after
```
cursor for pagination
External IDs are case-sensitive

适用场景：用户需要搜索、查看或管理联系人（用户和潜在客户）时

工具调用流程:

```
INTERCOM_SEARCH_CONTACTS
```
- 使用筛选条件搜索联系人 [必填]
```
INTERCOM_GET_A_CONTACT
```
- 获取特定联系人详情 [可选]
```
INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID
```
- 通过外部ID查找联系人 [可选]
```
INTERCOM_LIST_CONTACTS
```
- 列出所有联系人 [可选]

INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT

- 获取联系人标签 [可选]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT

- 获取联系人所属分组 [可选]

```
INTERCOM_DETACH_A_CONTACT
```
- 将联系人从公司中移除 [可选]

关键参数:

```
contact_id
```
: 用于检索的联系人ID
```
external_id
```
: 用于查找的外部系统ID
```
query
```
: 包含
```
field
```
、
```
operator
```
、
```
value
```
的搜索筛选对象
```
pagination
```
: 包含
```
per_page
```
和
```
starting_after
```
游标分页对象

注意事项:

SEARCH_CONTACTS使用结构化查询筛选，而非自由文本；格式为
```
{field, operator, value}
```
支持的操作符：
```
=
```
、
```
!=
```
、
```
>
```
、
```
<
```
、
```
~
```
（包含）、
```
!~
```
（不包含）、
```
IN
```
、
```
NIN
```
联系人类型分为'user'（已识别用户）或'lead'（匿名潜在客户）
LIST_CONTACTS返回分页结果；使用
```
starting_after
```
游标进行分页
外部ID区分大小写

4. Manage Admins and Teams

4. 管理员与团队管理

When to use: User wants to list workspace admins or identify specific admins

Tool sequence:

```
INTERCOM_LIST_ALL_ADMINS
```
- List all admins and teams [Required]
```
INTERCOM_IDENTIFY_AN_ADMIN
```
- Get specific admin details [Optional]

Key parameters:

```
admin_id
```
: Admin ID for identification

Pitfalls:

LIST_ALL_ADMINS returns both admins and teams
Admin IDs are required for conversation replies, assignment, close, and reopen
Teams appear in the admins list with
```
type: 'team'
```

适用场景：用户需要列出工作区管理员或查找特定管理员时

工具调用流程:

```
INTERCOM_LIST_ALL_ADMINS
```
- 列出所有管理员和团队 [必填]
```
INTERCOM_IDENTIFY_AN_ADMIN
```
- 获取特定管理员详情 [可选]

关键参数:

```
admin_id
```
: 用于查找的管理员ID

注意事项:

LIST_ALL_ADMINS会同时返回管理员和团队信息
对话回复、分配、关闭和重新打开操作需要管理员ID
团队在管理员列表中以
```
type: 'team'
```
标识

5. View Segments and Counts

5. 用户分组与统计数据查看

When to use: User wants to view segments or get aggregate counts

Tool sequence:

```
INTERCOM_LIST_SEGMENTS
```
- List all segments [Optional]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT

- Segments for a contact [Optional]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES

- Segments for a company [Optional]

```
INTERCOM_GET_COUNTS
```
- Get aggregate counts [Optional]

Key parameters:

```
contact_id
```
: Contact ID for segment lookup
```
company_id
```
: Company ID for segment lookup
```
type
```
: Count type ('conversation', 'company', 'user', 'tag', 'segment')
```
count
```
: Sub-count type

Pitfalls:

GET_COUNTS returns approximate counts, not exact numbers
Segment membership is computed; changes may not reflect immediately

适用场景：用户需要查看用户分组或获取聚合统计数据时

工具调用流程:

```
INTERCOM_LIST_SEGMENTS
```
- 列出所有用户分组 [可选]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT

- 获取联系人所属分组 [可选]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES

- 获取公司所属分组 [可选]

```
INTERCOM_GET_COUNTS
```
- 获取聚合统计数据 [可选]

关键参数:

```
contact_id
```
: 用于查找分组的联系人ID
```
company_id
```
: 用于查找分组的公司ID
```
type
```
: 统计类型（'conversation'、'company'、'user'、'tag'、'segment'）
```
count
```
: 子统计类型

注意事项:

GET_COUNTS返回的是近似统计值，而非精确数字
用户分组的成员信息是计算得出的；变更可能不会立即生效

6. Manage Companies

6. 公司管理

When to use: User wants to list companies or manage company-contact relationships

Tool sequence:

```
INTERCOM_LIST_ALL_COMPANIES
```
- List all companies [Required]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES

- Get company segments [Optional]

```
INTERCOM_DETACH_A_CONTACT
```
- Remove contact from company [Optional]

Key parameters:

```
company_id
```
: Company ID
```
contact_id
```
: Contact ID for detachment
```
page
```
: Page number for pagination
```
per_page
```
: Results per page

Pitfalls:

Company-contact relationships are managed through contact endpoints
DETACH_A_CONTACT removes the contact-company association, not the contact itself

适用场景：用户需要列出公司或管理公司与联系人的关联关系时

工具调用流程:

```
INTERCOM_LIST_ALL_COMPANIES
```
- 列出所有公司 [必填]

INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES

- 获取公司所属分组 [可选]

```
INTERCOM_DETACH_A_CONTACT
```
- 将联系人从公司中移除 [可选]

关键参数:

```
company_id
```
: 公司ID
```
contact_id
```
: 要移除的联系人ID
```
page
```
: 分页页码
```
per_page
```
: 每页结果数量

注意事项:

公司与联系人的关联关系通过联系人端点进行管理
DETACH_A_CONTACT仅移除联系人与公司的关联关系，不会删除联系人本身

Common Patterns

通用模式

Search Query Filters

搜索查询筛选条件

Single filter:

json

{
  "field": "email",
  "operator": "=",
  "value": "user@example.com"
}

Multiple filters (AND):

json

{
  "operator": "AND",
  "value": [
    {"field": "role", "operator": "=", "value": "user"},
    {"field": "created_at", "operator": ">", "value": 1672531200}
  ]
}

Supported fields for contacts: email, name, role, created_at, updated_at, signed_up_at, last_seen_at, external_id

Supported fields for conversations: created_at, updated_at, source.type, state, open, read

单个筛选条件:

json

{
  "field": "email",
  "operator": "=",
  "value": "user@example.com"
}

多个筛选条件（逻辑与）:

json

{
  "operator": "AND",
  "value": [
    {"field": "role", "operator": "=", "value": "user"},
    {"field": "created_at", "operator": ">", "value": 1672531200}
  ]
}

联系人支持的筛选字段: email、name、role、created_at、updated_at、signed_up_at、last_seen_at、external_id

对话支持的筛选字段: created_at、updated_at、source.type、state、open、read

Pagination

分页处理

Most list endpoints use cursor-based pagination
Check response for
```
pages.next
```
with
```
starting_after
```
cursor
Pass cursor in
```
pagination.starting_after
```
for next page
Continue until
```
pages.next
```
is null

大多数列表端点使用基于游标的分页方式
检查响应中的
```
pages.next
```
获取
```
starting_after
```
游标
将游标传入
```
pagination.starting_after
```
以获取下一页数据
直到
```
pages.next
```
为null时停止分页

Admin ID Resolution

管理员ID获取流程

1. Call INTERCOM_LIST_ALL_ADMINS to get all admins
2. Find the desired admin by name or email
3. Use admin.id for replies, assignments, and state changes

1. 调用INTERCOM_LIST_ALL_ADMINS获取所有管理员信息
2. 通过名称或邮箱找到目标管理员
3. 使用admin.id进行回复、分配和状态变更操作

Known Pitfalls

常见问题

Admin ID Requirement:

Admin ID is required for: reply (as admin), assign, close, reopen
Always resolve admin IDs first with LIST_ALL_ADMINS

HTML Content:

Conversation bodies are HTML
Plain text is auto-wrapped in paragraph tags
Sanitize HTML input to prevent rendering issues

Idempotency:

Replies and conversation creation are not idempotent
Duplicate sends can occur on retry or timeout
Track message IDs to prevent duplicates

Rate Limits:

Default: ~1000 requests per minute (varies by plan)
429 responses include rate limit headers
Implement exponential backoff for retries

管理员ID必填项:

以下操作必须提供管理员ID：管理员回复、分配、关闭、重新打开对话
请始终先通过LIST_ALL_ADMINS获取管理员ID

HTML内容处理:

对话内容为HTML格式
纯文本会自动被段落标签包裹
请对HTML输入进行清理，避免渲染问题

幂等性问题:

回复和对话创建操作不具备幂等性
重试或超时可能导致重复发送
需跟踪消息ID以避免重复发送

速率限制:

默认限制：约每分钟1000次请求（根据套餐不同有所变化）
429响应中包含速率限制头部信息
重试时请使用指数退避策略

Quick Reference

快速参考

Task	Tool Slug	Key Params
List conversations	INTERCOM_LIST_CONVERSATIONS	(pagination)
Search conversations	INTERCOM_SEARCH_CONVERSATIONS	query
Get conversation	INTERCOM_GET_CONVERSATION	id
Create conversation	INTERCOM_CREATE_CONVERSATION	from, body
Reply to conversation	INTERCOM_REPLY_TO_CONVERSATION	conversation_id, body, admin_id
Assign conversation	INTERCOM_ASSIGN_CONVERSATION	conversation_id, admin_id, assignee_id
Close conversation	INTERCOM_CLOSE_CONVERSATION	id, admin_id
Reopen conversation	INTERCOM_REOPEN_CONVERSATION	id, admin_id
Search contacts	INTERCOM_SEARCH_CONTACTS	query
Get contact	INTERCOM_GET_A_CONTACT	contact_id
Contact by external ID	INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID	external_id
List contacts	INTERCOM_LIST_CONTACTS	(pagination)
Contact tags	INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT	contact_id
Contact segments	INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT	contact_id
Detach contact	INTERCOM_DETACH_A_CONTACT	contact_id, company_id
List admins	INTERCOM_LIST_ALL_ADMINS	(none)
Identify admin	INTERCOM_IDENTIFY_AN_ADMIN	admin_id
List segments	INTERCOM_LIST_SEGMENTS	(none)
Company segments	INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES	company_id
Get counts	INTERCOM_GET_COUNTS	type, count
List companies	INTERCOM_LIST_ALL_COMPANIES	page, per_page

任务	工具标识	关键参数
列出对话	INTERCOM_LIST_CONVERSATIONS	(分页参数)
搜索对话	INTERCOM_SEARCH_CONVERSATIONS	query
获取对话详情	INTERCOM_GET_CONVERSATION	id
创建对话	INTERCOM_CREATE_CONVERSATION	from, body
回复对话	INTERCOM_REPLY_TO_CONVERSATION	conversation_id, body, admin_id
分配对话	INTERCOM_ASSIGN_CONVERSATION	conversation_id, admin_id, assignee_id
关闭对话	INTERCOM_CLOSE_CONVERSATION	id, admin_id
重新打开对话	INTERCOM_REOPEN_CONVERSATION	id, admin_id
搜索联系人	INTERCOM_SEARCH_CONTACTS	query
获取联系人详情	INTERCOM_GET_A_CONTACT	contact_id
通过外部ID查找联系人	INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID	external_id
列出联系人	INTERCOM_LIST_CONTACTS	(分页参数)
获取联系人标签	INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT	contact_id
获取联系人所属分组	INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT	contact_id
移除联系人与公司关联	INTERCOM_DETACH_A_CONTACT	contact_id, company_id
列出管理员	INTERCOM_LIST_ALL_ADMINS	(无)
获取管理员详情	INTERCOM_IDENTIFY_AN_ADMIN	admin_id
列出用户分组	INTERCOM_LIST_SEGMENTS	(无)
获取公司所属分组	INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES	company_id
获取统计数据	INTERCOM_GET_COUNTS	type, count
列出公司	INTERCOM_LIST_ALL_COMPANIES	page, per_page