pipedrive-automation

通过 Rube MCP 自动化 Pipedrive

通过 Composio 的 Pipedrive 工具包，自动化 Pipedrive CRM 工作流，包括交易管理、联系人和组织操作、活动安排、备注，以及管道和阶段查询。

前提条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过工具包 pipedrive，使用 RUBE_MANAGE_CONNECTIONS 建立有效的 Pipedrive 连接
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

使用现有的已批准 Rube 连接；仅添加端点并不会完成 Pipedrive 身份验证。仅在请求范围内使用受支持的主机设置和身份验证流程。

1. 确认 RUBE_SEARCH_TOOLS 可以响应，以验证 Rube MCP 是否可用
2. 使用工具包 pipedrive 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请访问返回的身份验证链接，完成 Pipedrive OAuth
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

以下历史工具、字段类型和分页默认值均需通过当前架构发现。执行请求的变更前，请核实实际账户、实体、可见性、币种和时区；不要仅仅因为模糊的名称搜索没有返回匹配结果就创建联系人。限制检索的个人数据和备注，并在重试前核实结果未知的写入操作。

核心工作流

1. 创建和管理交易

适用场景：用户想要创建新交易、更新现有交易，或查看销售管道中的交易详情。

工具调用顺序：

1. PIPEDRIVE_SEARCH_ORGANIZATIONS - 查找要关联到交易的现有组织 [可选]
2. PIPEDRIVE_ADD_AN_ORGANIZATION - 如果没有找到组织，则创建组织 [可选]
3. PIPEDRIVE_SEARCH_PERSONS - 查找要关联的现有联系人 [可选]
4. PIPEDRIVE_ADD_A_PERSON - 如果没有找到联系人，则创建联系人 [可选]
5. PIPEDRIVE_GET_ALL_PIPELINES - 获取管道 ID [前置条件]
6. PIPEDRIVE_GET_ALL_STAGES - 获取管道中的阶段 ID [前置条件]
7. PIPEDRIVE_ADD_A_DEAL - 创建包含标题、金额、org_id、person_id 和 stage_id 的交易 [必需]
8. PIPEDRIVE_UPDATE_A_DEAL - 创建后修改交易属性 [可选]
9. PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL - 附加行项目或产品 [可选]

关键参数：

• title：交易标题（创建时必需）
• value：交易金额
• currency：3 个字母的 ISO 币种代码（例如，“USD”）
• pipeline_id / stage_id：用于指定管道位置的数字 ID
• org_id / person_id：关联组织和联系人
• status：“open”、“won”或“lost”
• expected_close_date：格式为 YYYY-MM-DD

注意事项：

• title 是 PIPEDRIVE_ADD_A_DEAL 唯一的必填字段；其他字段均为可选
• 自定义字段在响应中会显示为较长的哈希键；使用 dealFields 端点进行映射
• PIPEDRIVE_UPDATE_A_DEAL 需要交易的数字 id
• 将 status 设为“lost”时，还必须提供 lost_reason

2. 管理联系人（个人和组织）

使用场景：用户想在 Pipedrive 中创建、更新、搜索或列出联系人和公司。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS - 按姓名、电子邮件或电话号码搜索现有个人 [前置步骤]
2. PIPEDRIVE_ADD_A_PERSON - 如果未找到，则创建新联系人 [必需]
3. PIPEDRIVE_UPDATE_A_PERSON - 修改现有联系人的详细信息 [可选]
4. PIPEDRIVE_GET_DETAILS_OF_A_PERSON - 获取完整的联系人记录 [可选]
5. PIPEDRIVE_SEARCH_ORGANIZATIONS - 搜索现有组织 [前置步骤]
6. PIPEDRIVE_ADD_AN_ORGANIZATION - 如果未找到，则创建新组织 [必需]
7. PIPEDRIVE_UPDATE_AN_ORGANIZATION - 修改组织属性 [可选]
8. PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION - 获取完整的组织记录 [可选]

关键参数：

• name：创建个人和组织时均为必填项
• email：由包含 value、label、primary 字段的对象组成的数组，适用于个人
• phone：由包含 value、label、primary 字段的对象组成的数组，适用于个人
• org_id：将个人关联到组织
• visible_to：1 = 仅所有者可见，3 = 整个公司可见
• term：SEARCH_PERSONS / SEARCH_ORGANIZATIONS 的搜索词（至少 2 个字符）

注意事项：

• PIPEDRIVE_ADD_AN_ORGANIZATION 可能会与现有组织自动合并；请检查 response.additional_data.didMerge
• 电子邮件和电话号码字段是对象数组，而非普通字符串：[{"value": "[email protected]", "label": "work", "primary": true}]
• PIPEDRIVE_SEARCH_PERSONS 不支持 * 或 @ 等通配符；请使用 PIPEDRIVE_GET_ALL_PERSONS 列出所有个人
• 通过 PIPEDRIVE_DELETE_A_PERSON 或 PIPEDRIVE_DELETE_AN_ORGANIZATION 删除属于软删除，数据会保留 30 天，之后永久删除

3. 安排和跟踪活动

使用场景：用户想创建与交易、联系人或组织关联的电话、会议、任务或其他活动。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS 或 PIPEDRIVE_GET_DETAILS_OF_A_DEAL - 获取关联实体的 ID [前置步骤]
2. PIPEDRIVE_ADD_AN_ACTIVITY - 使用主题、类型和到期日创建活动 [必需]
3. PIPEDRIVE_UPDATE_AN_ACTIVITY - 修改活动详情或将活动标记为已完成 [可选]
4. PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY - 获取活动记录 [可选]
5. PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER - 列出用户的活动 [可选]

关键参数：

• subject：活动标题（必填）
• type：活动类型键字符串，例如 "call"、"meeting"、"task"、"email"（必填）
• due_date：格式为 YYYY-MM-DD
• due_time：格式为 HH:MM
• duration：格式为 HH:MM（例如，"00:30" 表示 30 分钟）
• deal_id / person_id / org_id：关联相关实体
• done：0 = 未完成，1 = 已完成

注意事项：

• PIPEDRIVE_ADD_AN_ACTIVITY 的 subject 和 type 均为必填项
• type 必须与账户中现有 ActivityTypes 的 key_string 匹配
• done 是整数（0 或 1），不是布尔值
• 响应的 additional_data 中包含 more_activities_scheduled_in_context

4. 添加和管理备注

使用场景：用户想要为交易、人员、组织、潜在客户或项目附加备注。

工具调用顺序：

1. PIPEDRIVE_SEARCH_PERSONS 或 PIPEDRIVE_GET_DETAILS_OF_A_DEAL - 解析实体 ID［前置条件］
2. PIPEDRIVE_ADD_A_NOTE - 创建与实体关联的 HTML 内容备注［必需］
3. PIPEDRIVE_UPDATE_A_NOTE - 修改备注内容［可选］
4. PIPEDRIVE_GET_ALL_NOTES - 按实体筛选备注列表［可选］
5. PIPEDRIVE_GET_ALL_COMMENTS_FOR_A_NOTE - 获取备注的评论［可选］

关键参数：

• content：HTML 格式的备注正文（必填）
• deal_id / person_id / org_id / lead_id / project_id：必须至少关联一个实体
• pinned_to_deal_flag / pinned_to_person_flag：列出备注时筛选已置顶的备注

注意事项：

• content 为必填项，支持 HTML；纯文本也可使用，但会在服务端进行清理
• 必须提供 deal_id、person_id、org_id、lead_id 或 project_id 中的至少一个
• PIPEDRIVE_GET_ALL_NOTES 默认返回所有实体的备注；使用实体 ID 参数进行筛选

5. 查询销售渠道和阶段

使用场景：用户想要查看销售渠道、阶段，或销售渠道／阶段中的交易。

工具调用顺序：

1. PIPEDRIVE_GET_ALL_PIPELINES - 列出所有销售渠道及其 ID［必需］
2. PIPEDRIVE_GET_ONE_PIPELINE - 获取特定销售渠道的详情和交易摘要［可选］
3. PIPEDRIVE_GET_ALL_STAGES - 列出所有阶段，可按销售渠道筛选［必需］
4. PIPEDRIVE_GET_ONE_STAGE - 获取特定阶段的详情［可选］
5. PIPEDRIVE_GET_DEALS_IN_A_PIPELINE - 列出某销售渠道各阶段中的所有交易［可选］
6. PIPEDRIVE_GET_DEALS_IN_A_STAGE - 列出特定阶段中的交易［可选］

关键参数：

• id：销售渠道或阶段 ID（单项端点必填）
• pipeline_id：按销售渠道筛选阶段
• totals_convert_currency：3 位货币代码，或用于换算总额的 "default_currency"
• get_summary：设为 1，以在销售渠道响应中获取交易摘要

注意事项：

• PIPEDRIVE_GET_ALL_PIPELINES 不接受参数；会返回所有销售渠道
• 除非指定 pipeline_id，否则 PIPEDRIVE_GET_ALL_STAGES 会返回所有销售渠道的阶段
• 仅当设置了 totals_convert_currency 时，销售渠道摘要中的交易数量才会使用 per_stages_converted

常见模式

ID 解析

执行操作前，始终将显示名称解析为数字 ID：

• 组织名称 -> org_id：使用 term 参数调用 PIPEDRIVE_SEARCH_ORGANIZATIONS
• 人员名称 -> person_id：使用 term 参数调用 PIPEDRIVE_SEARCH_PERSONS
• 销售渠道名称 -> pipeline_id：调用 PIPEDRIVE_GET_ALL_PIPELINES，然后按名称匹配
• 阶段名称 -> stage_id：使用 pipeline_id 调用 PIPEDRIVE_GET_ALL_STAGES，然后按名称匹配

分页

分页方式取决于 API／工具版本；请遵循发现的游标或偏移量约定。历史上的偏移量分页示例：

• 使用 start（偏移量）和 limit（页面大小）参数
• 检查 additional_data.pagination.more_items_in_collection，以确定是否还有更多页面
• 将 additional_data.pagination.next_start 用作下一页的 start 值
• 某些端点的默认 limit 约为 500；请明确设置，以确保分页行为可预测

已知注意事项

ID 格式

• 所有实体 ID（交易、人员、组织、活动、销售渠道、阶段）均为数字整数
• 潜在客户 ID 为 UUID 字符串，而非整数
• 自定义字段键是较长的字母数字哈希值（例如 "a1b2c3d4e5f6..."）

速率限制

• Pipedrive 对每家公司实施 API 速率限制；批量操作应控制调用频率
• PIPEDRIVE_GET_ALL_PERSONS 和 PIPEDRIVE_GET_ALL_ORGANIZATIONS 可能返回大型数据集；务必分页

参数特殊行为

• 联系人上的邮箱和电话是对象数组，而非普通字符串
• visible_to 为数字：1 = 仅所有者，3 = 整个公司，5 = 特定组
• 活动上的 done 是整数 0/1，而非布尔值 true/false
• 创建组织时可能会静默地自动合并重复项；请检查响应中的 didMerge
• PIPEDRIVE_SEARCH_PERSONS 要求至少 2 个字符，且不支持通配符

响应结构

• 自定义字段在响应中显示为哈希键；请通过相应的 Fields 端点进行映射
• 在包装执行中，响应通常将数据嵌套在 response.data.data 下
• 搜索结果位于 response.data.items 下，而非顶层

快速参考

任务	工具 Slug	关键参数
创建交易	PIPEDRIVE_ADD_A_DEAL	title、value、org_id、stage_id
更新交易	PIPEDRIVE_UPDATE_A_DEAL	id、status、value、stage_id
获取交易详情	PIPEDRIVE_GET_DETAILS_OF_A_DEAL	id
搜索联系人	PIPEDRIVE_SEARCH_PERSONS	term、fields
添加联系人	PIPEDRIVE_ADD_A_PERSON	name、email、phone、org_id
更新联系人	PIPEDRIVE_UPDATE_A_PERSON	id、name、email
获取联系人详情	PIPEDRIVE_GET_DETAILS_OF_A_PERSON	id
列出所有联系人	PIPEDRIVE_GET_ALL_PERSONS	start、limit、filter_id
搜索组织	PIPEDRIVE_SEARCH_ORGANIZATIONS	term、fields
添加组织	PIPEDRIVE_ADD_AN_ORGANIZATION	name、visible_to
更新组织	PIPEDRIVE_UPDATE_AN_ORGANIZATION	id、name、address
获取组织详情	PIPEDRIVE_GET_DETAILS_OF_AN_ORGANIZATION	id
添加活动	PIPEDRIVE_ADD_AN_ACTIVITY	subject、type、due_date、deal_id
更新活动	PIPEDRIVE_UPDATE_AN_ACTIVITY	id、done、due_date
获取活动详情	PIPEDRIVE_GET_DETAILS_OF_AN_ACTIVITY	id
列出用户活动	PIPEDRIVE_GET_ALL_ACTIVITIES_ASSIGNED_TO_A_PARTICULAR_USER	user_id、start、limit
添加备注	PIPEDRIVE_ADD_A_NOTE	content、deal_id 或 person_id
列出备注	PIPEDRIVE_GET_ALL_NOTES	deal_id、person_id、start、limit
列出管道	PIPEDRIVE_GET_ALL_PIPELINES	（无）
获取管道详情	PIPEDRIVE_GET_ONE_PIPELINE	id
列出阶段	PIPEDRIVE_GET_ALL_STAGES	pipeline_id
管道中的交易	PIPEDRIVE_GET_DEALS_IN_A_PIPELINE	id、stage_id
阶段中的交易	PIPEDRIVE_GET_DEALS_IN_A_STAGE	id、start、limit
将产品添加到交易	PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL	id、product_id、item_price

使用时机

此技能适用于执行概述中描述的工作流或操作。

示例

用户请求：

通过 Rube MCP（Composio）自动化 Pipedrive CRM 操作，包括交易、联系人、组织、活动、备注和管道管理。

限制

• 仅在任务明确符合上述范围时使用此技能。
• 请勿将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。