HubSpot
将 HubSpot 用作工作区的 CRM：直接写入商机、任务与备注，在时间线上记录外联活动，并在 HubSpot 显示联系人已进入后续阶段时停止相关营销活动。
HubSpot 模式让 HubSpot 成为工作区的 CRM。你在 Warmbly 中看到的商机、销售管道、任务和备注，都是 HubSpot 的记录；客户触达活动也会记录到各联系人的 HubSpot 时间线上。
切换到 HubSpot
打开集成 > HubSpot，选择连接。
登录 HubSpot，选择账户并批准权限。
完成设置向导。每个问题都有可用的默认值，因此可以不作修改直接完成。
结束向导。首次拉取运行时，控制台会逐渐填入数据，通常只需一两分钟。
使用须知
- 在 Warmbly 中进行的每次修改都会先写入 HubSpot。如果 HubSpot 拒绝，任何内容都不会保存。
- 在 HubSpot 中创建商机、进入你选择的生命周期阶段，或选择不再接收邮件，都会暂停该联系人的营销活动。
- 销售管道和阶段只能在 HubSpot 中管理。
- 支持免费版 HubSpot。
- 切回原模式或断开连接，都不会删除任一侧的数据。
工作区可以使用 Warmbly 自带的 CRM，也可以使用 HubSpot。在 HubSpot 模式中，HubSpot 是权威数据源。你在 Warmbly 中看到的商机、销售管道、任务和备注都是 HubSpot 的记录，镜像到 Warmbly 以确保列表、搜索和看板响应迅速；在 Warmbly 中执行的每次修改都会先写入 HubSpot。客户触达活动记录到各联系人的 HubSpot 时间线；当联系人转化为商机或客户时，HubSpot 可以停止营销活动。
基础 HubSpot 连接无需启用 HubSpot 模式即可使用，包括从自动化流程创建或更新联系人，以及推送到 CRM。本页介绍完整的 HubSpot 模式。
- 商机、销售管道、任务和备注都属于 HubSpot。 在 Warmbly 中创建、移动或编辑商机时，会先写入 HubSpot，再保存到这里。如果 HubSpot 拒绝，例如缺少必填属性或权限，界面会显示 HubSpot 给出的原因，且不保存任何修改。
- 客户触达活动写入 HubSpot 时间线。 发送和回复记录为电子邮件活动，退信和退订也会记录，已预约会议则成为 HubSpot 会议。
- HubSpot 联系人上的“Warmbly”属性组保存每位联系人的触达状态，供 HubSpot 用户据此筛选列表、构建报表和触发工作流。
- HubSpot 可以停止触达。 在 HubSpot 中创建商机、进入你指定的生命周期阶段，或选择不再接收邮件，都会暂停该联系人的营销活动。
- 联系人面板展示 HubSpot 信息。 在联系人抽屉和收件箱中，可查看 HubSpot 负责人、生命周期阶段、潜在客户状态、公司以及你选择的属性，并可直接修改负责人、生命周期阶段和潜在客户状态。
- 打开集成 > HubSpot并选择连接。登录 HubSpot，选择账户并批准权限。连接操作需要由有权在该 HubSpot 账户中安装应用的人完成。
- 设置向导随即打开。每个问题都有可用的默认值，可以不作修改直接完成，稍后再调整。向导会询问要记录哪些活动、是否允许 Warmbly 创建联系人和公司、积极回复触发什么操作、哪些规则停止触达、镜像哪些商机管道，以及联系人字段如何映射。
- 完成向导。Warmbly 会在 HubSpot 中创建 Warmbly 属性组，并开始首次拉取：先拉取负责人和销售管道，再拉取近期商机与任务。运行过程中，控制台逐渐填入数据，通常只需一两分钟。
设置完成后，同一页面提供配置选项和同步健康度面板。修改设置需要 manage_settings 权限。
HubSpot 模式推出前建立的连接需要重新连接
早期 HubSpot 连接只申请了联系人权限。HubSpot 模式还需要公司、商机、负责人和联系人架构权限，因此页面会要求先重新连接再切换；完成之前，切换会以 crm_reauth_required 被拒绝。
| 记录 | 方向 | 方式 |
|---|---|---|
| 商机 | 双向 | Warmbly 直接写入 HubSpot；每分钟拉取 HubSpot 中的变更 |
| 销售管道和阶段 | HubSpot 到 Warmbly | 仅在 HubSpot 中管理；每 30 分钟拉取一次，若收到的商机位于尚未知晓的阶段，则提前拉取 |
| 任务 | 双向 | Warmbly 直接写入；每分钟拉取由已匹配成员负责的任务 |
| 备注 | 双向 | Warmbly 直接写入；打开联系人时拉取其 HubSpot 备注 |
| 任务类型 | HubSpot 到 Warmbly | 固定使用 HubSpot 的类型：待办、电话、电子邮件、LinkedIn |
| 负责人 | HubSpot 到 Warmbly | 每 30 分钟拉取一次，并按电子邮件地址匹配成员 |
| 联系人 | 按字段双向同步 | 包括负责人、生命周期阶段、潜在客户状态、公司、退订及映射字段。参见联系人与字段映射 |
| 触达活动 | Warmbly 到 HubSpot | 参见记录到 HubSpot 的活动 |
Warmbly 只拉取上次之后发生变化的内容，因此每分钟拉取仍然保持轻量。打开 Warmbly 联系人时，也会立即刷新该联系人的 HubSpot 记录、商机、任务和备注。
商机与销售管道
销售管道页面只列出 HubSpot 管道。创建、重命名或删除管道或阶段会以 crm_managed_externally 被拒绝：请在 HubSpot 中修改，几分钟内就会同步到 Warmbly。在向导中可以将镜像范围限制为部分管道；其他管道中的商机不会镜像。
HubSpot 作为 CRM 期间，仅存在于 Warmbly 的管道中的商机会从商机表格和看板中隐藏。它们并未删除：将其复制到 HubSpot或切回原模式后即可再次看到。
HubSpot 将赢单和输单表示为阶段，而非独立状态。在 Warmbly 中将商机标记为赢单或输单时，会将其移到该管道的第一个“已成交”或“已丢单”阶段；将商机移入已关闭阶段也会设置其状态。阶段携带 HubSpot 的关闭标志、赢单标志和成交概率。如果商机的 HubSpot 负责人不是工作区成员，仍会显示该负责人的姓名。
自动化流程通过创建商机或移动商机阶段操作生成的商机也会写入 HubSpot，但通过同步队列处理，而非立即执行。
任务
任务页面显示 HubSpot 用户负责、且该用户已匹配到工作区成员的 HubSpot 任务。首次拉取包含最近 90 天发生过变化的任务。打开联系人时，会拉取其自身的任务，无论由谁负责。
| Warmbly | HubSpot |
|---|---|
优先级 low、medium、high、urgent | Low、Medium、High（urgent 写为 High） |
状态 pending、in progress、completed、cancelled | Not started、In progress、Completed、Deferred |
| 被分配成员 | 任务负责人。未匹配 HubSpot 负责人的成员不能被分配任务（crm_owner_unmapped） |
创建、编辑或删除任务类型会以 crm_managed_externally 被拒绝，因为 HubSpot 的任务类型是固定的。Warmbly 自动创建的任务也会写入 HubSpot，例如由回复产生的跟进任务，以及自动化流程中的创建任务。
Warmbly 联系人通过电子邮件地址与 HubSpot 联系人关联。以下情况会建立关联：Warmbly 向联系人发信、你打开联系人、HubSpot 修改了 Warmbly 已有该地址的联系人，以及从 HubSpot 列表导入之后。
当 Warmbly 向 HubSpot 尚未收录的人发信时，会创建 HubSpot 联系人，默认开启。开启创建公司后（同样默认开启），新联系人会关联到与其电子邮件域名对应的公司；若 HubSpot 中没有该公司，则创建公司。gmail.com 等免费邮箱域名绝不会变成公司。如果关闭创建联系人，HubSpot 中不存在的联系人就不会在那里记录活动。
每个映射字段都有同步方向：
| 方向 | 行为 |
|---|---|
| 推送 | 在 Warmbly 中编辑联系人时，以及每次向其发信时，将字段写入 HubSpot |
| 拉取 | 将 HubSpot 中的变更复制到 Warmbly 联系人 |
| 双向 | 最近的修改优先：HubSpot 中的编辑复制到 Warmbly，Warmbly 中的编辑写入 HubSpot |
默认将名字、姓氏、公司和电话映射到 firstname、lastname、company 和 phone，方向均为双向。自定义字段使用 custom:<key> 映射。HubSpot 中的空值不会清空 Warmbly 字段，电子邮件地址也绝不会被 HubSpot 覆盖。
还可以选择最多 40 个额外 HubSpot 属性，显示在联系人面板中。
| Warmbly 中的事件 | HubSpot 中的记录 | 默认 |
|---|---|---|
| 发送营销活动邮件 | 包含主题和正文的出站电子邮件活动 | 开启 |
| 联系人回复 | 入站电子邮件活动 | 开启 |
| 邮件退信 | 已记录的邮件标记为 BOUNCED | 开启 |
| 联系人退订 | 联系人备注，并设置 warmbly_unsubscribed | 开启 |
| 通过 Calendly 或 Cal.com 预约会议 | HubSpot 会议 | 开启 |
| 打开邮件 | 更新 warmbly_last_opened_at，不新增时间线记录 | 关闭 |
| 点击链接 | 更新 warmbly_last_clicked_at，不新增时间线记录 | 关闭 |
每项电子邮件活动都会关联到联系人、其公司和所有未关闭的商机。如果发件邮箱所属成员已匹配 HubSpot 负责人，则活动负责人为该成员；否则使用联系人的负责人。活动会在数秒内记录，且完全不依赖你的 Webhook及其每分钟限额，因此大批量发送也能完整记录。
打开和点击记录默认关闭，因为邮件隐私代理和安全扫描器会自动打开与点击，容易让 HubSpot 时间线充满噪声。开启后，它们也只更新这两个属性，每位联系人每小时最多更新一次，且绝不会因此在 HubSpot 中创建联系人。
切换时，Warmbly 会在 HubSpot 中创建名为 Warmbly 的联系人属性组，并持续更新。此功能默认开启；关闭后会停止所有属性写入，包括打开和点击。你或 HubSpot 管理员已经修改过的属性会保持原样。
| 属性 | 内容 |
|---|---|
warmbly_status | contacted、replied、interested、not_interested、meeting_booked、bounced 或 unsubscribed。后续发送绝不会将已回复的联系人退回 contacted 状态 |
warmbly_last_campaign | 最近一次向联系人发送邮件的营销活动名称 |
warmbly_last_contacted_at | Warmbly 最近一次向联系人发信的时间 |
warmbly_last_replied_at | 联系人最近回复时间 |
warmbly_reply_intent | Warmbly 对最新回复的分类 |
warmbly_last_opened_at | 开启打开记录时，最近一次打开时间 |
warmbly_last_clicked_at | 开启点击记录时，最近一次点击时间 |
warmbly_unsubscribed | 联系人退订 Warmbly 触达邮件时设置 |
warmbly_link | 在 Warmbly 中打开该联系人的链接 |
HubSpot 负责人，即其用户，会按电子邮件地址匹配工作区成员。地址不一致时，可以在 HubSpot 页面手动选择成员；手动匹配会被保留，不会被邮箱匹配覆盖。匹配关系决定：
- 任务页面显示谁的任务
- 邮箱记录的电子邮件活动归谁所有
- 在 Warmbly 中将商机或任务分配给成员时，对应哪位 HubSpot 负责人
- Warmbly 卡片以谁的身份执行操作，从而决定 HubSpot 用户可以通过卡片做什么
回复被判定为感兴趣时，Warmbly 可以：
- 设置联系人的潜在客户状态，默认为
In progress - 设置其生命周期阶段，默认关闭。HubSpot 不允许生命周期阶段倒退；即使拒绝该变更，潜在客户状态仍会设置
- 在指定管道和阶段中创建商机，默认关闭。如果联系人已有未关闭的商机，则跳过
跟进任务沿用现有的回复跟进设置，并与其他任务一样写入 HubSpot。
当 HubSpot 表明联系人已进入下一阶段时，退出规则会暂停该联系人参与的所有营销活动，避免其已经成为商机或客户后仍收到跟进邮件。被暂停的潜在客户会持续保持暂停，直到有人恢复；暂停状态会显示原因，例如“已在 HubSpot 中创建商机”。
| 规则 | 默认 |
|---|---|
| 在 HubSpot 中创建与联系人关联的商机 | 开启。仅计算最近 48 小时创建的商机，因此首次拉取已有商机不会暂停任何人 |
| 联系人的生命周期阶段变为你指定的阶段 | 开启，针对 Opportunity 和 Customer |
| 联系人在 HubSpot 中选择不再接收邮件 | 开启。地址会加入禁止发送名单 |
导入保护措施
导入保护规则决定从 HubSpot 列表导入时排除哪些人：
| 保护规则 | 默认 |
|---|---|
| 跳过已选择不再接收邮件的联系人 | 开启 |
| 跳过处于这些生命周期阶段的联系人 | 开启，针对 Customer 和 Evangelist |
| 跳过已有未关闭商机的联系人 | 开启 |
| 跳过由工作区之外的人负责的联系人 | 关闭 |
以下两项功能将 Warmbly 带入 HubSpot，销售人员无需切换标签页即可处理联系人：
- 每个联系人记录上的 Warmbly 卡片显示联系人的 Warmbly 状态、所参与的各营销活动及当前步骤，以及潜在客户暂停的原因。可以从卡片将联系人加入活动、暂停或恢复其所有活动，并在 Warmbly 中打开联系人。如果联系人尚不存在于 Warmbly，加入时会根据 HubSpot 记录创建。
- “加入 Warmbly 营销活动”工作流操作将工作流中的联系人加入指定活动，让 HubSpot 列表、表单或生命周期变更自动为触达流程提供联系人。已在 HubSpot 中选择不再接收邮件的联系人会被跳过；操作会在输出中报告结果，供工作流下一步使用。
卡片以查看它的 HubSpot 用户所匹配的 Warmbly 成员身份和角色运行，参见负责人：
| 卡片中的操作 | 成员需要的权限 |
|---|---|
| 查看联系人的 Warmbly 状态和营销活动 | 查看营销活动和查看联系人 |
| 加入营销活动 | 管理营销活动和管理联系人 |
| 暂停或恢复营销活动 | 管理营销活动 |
如果 HubSpot 用户没有匹配成员，或对应成员仍处于受邀状态、被禁止登录、缺少权限，卡片会说明原因，且不会修改任何内容。工作流操作没有查看者：由有权编辑 HubSpot 工作流的人设置，并以工作区所有者身份执行。
卡片和工作流操作要求该 HubSpot 账户恰好在一个 Warmbly 工作区中启用 HubSpot 模式。如果多个工作区都以 HubSpot 模式连接该账户，两项功能都会拒绝执行，直到只剩一个工作区启用。
在 HubSpot 页面选择一个 HubSpot 列表。预览会统计将导入的人数，以及按原因划分的跳过人数：已退订、生命周期阶段、已有未关闭商机、由工作区之外的人负责、没有电子邮件地址，以及地址重复。继续后，列表会转为普通联系人导入，在常规导入审阅中选择营销活动、标签和重复处理方式并完成。
一次最多导入 25,000 位联系人；更大的列表会在该数量处截断，并在预览中说明。导入的联系人会在几分钟后与其 HubSpot 记录关联，确保首次发送记录到正确的人。
列表导入需要 HubSpot 的列表权限，该权限为可选项。没有该权限的连接会被要求重新连接并允许列表访问。
原先使用 Warmbly CRM 的工作区切换后，其自有商机、任务和备注还不存在于 HubSpot。HubSpot 页面会统计这些记录，并一次性复制你选择的类型：
- 商机移入第一个 HubSpot 管道。如果 HubSpot 存在同名阶段，就保留阶段；否则进入与商机状态匹配的第一个阶段，即进行中、赢单或输单
- 任务和备注会连同其联系人及商机关联一起在 HubSpot 中创建
已存在于 HubSpot 的记录不会重复复制，因此再次运行只会补齐遗漏项。切换后，如果编辑某个 Warmbly 商机、任务或备注，也会在当时将其创建到 HubSpot。
HubSpot 页面会显示等待处理的内容、最近运行中失败的内容、已镜像的记录数，以及各项拉取（负责人、管道、商机、任务、联系人）的最近运行时间和错误。立即同步启动一次完整拉取；30 秒内再次启动会以 crm_sync_running 被拒绝。
在控制台中修改时，会同步等待 HubSpot 写入。活动记录、自动化流程写入的记录以及复制操作通过队列处理；失败时以逐渐增长的间隔重试，从一分钟、五分钟、半小时到数小时，之后才标记为失败。失败项会保留在列表中 30 天，并提供通俗的原因说明。重试再次发送，丢弃则移除该项。
| 提示 | 处理方式 |
|---|---|
| 重新连接 HubSpot | HubSpot 已撤销 Warmbly 访问权限，或缺少某项权限。从集成重新连接，并批准全部权限 |
| HubSpot 拒绝修改 | 触发了 HubSpot 自身规则，界面显示其原始说明，例如商机缺少必填属性。在 HubSpot 或该记录中修复，然后重试 |
| 此记录已不存在于 HubSpot | 记录已在 HubSpot 中删除。丢弃该项 |
| 该成员尚未对应 HubSpot 用户 | 在负责人中将成员匹配到 HubSpot 负责人 |
| HubSpot 未响应 | HubSpot 响应缓慢或服务中断。系统会自动重试 |
Warmbly 对每个 HubSpot 账户的调用量都保持在 HubSpot 限额以内，约每 10 秒 90 次请求，并在所有 Warmbly 进程间共享额度；HubSpot 要求降速时，会等待并重试。
再次选择 Warmbly 作为 CRM，或断开 HubSpot，会停止同步和活动记录。任一侧都不会删除数据：已镜像的商机、管道、任务和备注留在 Warmbly，成为可编辑的普通记录；之前隐藏、仅属于 Warmbly 的管道会重新出现；HubSpot 保留所有已写入的内容。以后重新切换到同一个 HubSpot 账户时，会继续使用原有记录，不会创建重复项。
自托管实例使用自己的 HubSpot 应用。在 HubSpot 开发者账户中创建应用，然后：
- 将重定向 URL 设为
BACKEND_PUBLIC_URL加/integrations/oauth/callback；如果设置了INTEGRATIONS_OAUTH_REDIRECT_URL，则使用该值。 - 添加必需权限范围：
oauth、crm.objects.contacts.read、crm.objects.contacts.write、crm.objects.companies.read、crm.objects.companies.write、crm.objects.deals.read、crm.objects.deals.write、crm.objects.owners.read、crm.schemas.contacts.read和crm.schemas.contacts.write。将crm.lists.read和sales-email-read添加为可选权限范围。 - 在后端和消费者服务中设置
HUBSPOT_OAUTH_CLIENT_ID与HUBSPOT_OAUTH_CLIENT_SECRET，并设置APP_URL，让warmbly_link属性指向你的控制台。参见配置。
消费者服务负责每分钟拉取和同步队列，因此 HubSpot 模式无需来自 HubSpot 的入站流量。Webhook 为可选项：让应用订阅 contact.creation、contact.propertyChange、contact.deletion、deal.creation、deal.propertyChange 和 deal.deletion，目标 URL 为 <backend>/api/v1/integrations/hubspot/webhooks，即可在数秒内而非一分钟内获取变更。投递使用 HubSpot 的 X-HubSpot-Signature-v3 签名，基于 BACKEND_PUBLIC_URL 验证；它只会让下一次读取提前发生。Warmbly 始终从 HubSpot 自身读取记录，并且只有 HubSpot 明确回应记录已不存在时，才会移除商机或任务。
工作区导出包含 CRM 模式、设置选项、负责人匹配关系、Warmbly 记录与 HubSpot 记录的对应关系，以及各联系人的 HubSpot 详情，因此目标实例会继续更新同一批 HubSpot 记录，不会重复创建。同步队列和拉取检查点不会迁移；目标实例会开始自己的拉取。除非目标使用同一个 HubSpot 应用，且归档包含凭据，否则需在目标实例重新连接 HubSpot。
支持免费版 HubSpot 吗？ 支持。联系人、公司、商机、任务、备注、负责人和自定义联系人属性都属于 HubSpot 免费 CRM。列表和读取邮件权限是可选的，因此无法授予它们的账户也能连接；只有列表导入在没有列表权限时不可用。
Warmbly 会请求哪些权限？ 对联系人、公司和商机的读写权限；读取负责人；以及联系人架构的读写权限，用于创建 Warmbly 属性组。列表和邮件读取权限作为可选项请求。
为什么默认关闭打开记录？ 邮件隐私代理和安全扫描器会自动打开与点击，因此打开只是较弱的信号，还会淹没时间线。开启后，也只更新 warmbly_last_opened_at 和 warmbly_last_clicked_at。
断开连接后，数据会怎样？ 所有已镜像的内容都作为普通记录保留在 Warmbly 中，HubSpot 中也不会移除任何内容。参见切回原模式与断开连接。
可以在 Warmbly 中编辑销售管道吗？ HubSpot 作为 CRM 期间不可以。请在 HubSpot 中编辑，几分钟内就会更新到 Warmbly。
每位成员都需要 HubSpot 席位吗？ 不需要。没有匹配负责人的成员仍可查看商机、任务和备注，只是不能被分配 HubSpot 商机或任务；其邮箱产生的邮件活动会记录在联系人的负责人名下。