Salesforce

Salesforce 集成让组织与 Warmbly 自动保持同步，无需人工复制数据。营销活动邮件、回复和会议以已完成 Task 的形式出现在 Lead（潜在客户）或 Contact（联系人）时间线上；回复可以更新 Lead Status，任一侧拒收会让双方停止发信。每个联系人抽屉和收件箱会话还会显示 Salesforce 中的负责人及未关闭商机。

• 支持 API 的 Salesforce 版本：Enterprise、Unlimited、Performance、Developer，或购买 API 附加功能的 Professional。Essentials 没有 API。
• 用于连接的用户需要 API Enabled（启用 API）权限，对 Leads、Contacts、Tasks 具有读取和编辑权限，对 Accounts、Opportunities、Campaigns 具有读取权限。字段级安全仍然适用，用户无权编辑的字段不能回写。
• 如果组织限制已连接应用，管理员需在 Setup > Connected Apps OAuth Usage（设置 > 已连接应用 OAuth 使用情况） 中批准 Warmbly 一次。自 2025 年 9 月起，除非用户有权批准未安装应用，否则 Salesforce 会拒绝尚无人批准的应用。

Warmbly 以连接用户身份执行。创建的记录和 Task 按下文规则分配所有权，但所有调用都使用该用户的访问权限，因此最清晰的方案是创建具备上述权限的专用集成用户。

1. 打开集成 > Salesforce > 连接。
2. 选择生产环境、沙盒，或为 acme.my.salesforce.com 这样的 My Domain 选择自定义域名。
3. 登录 Salesforce 并批准访问。Warmbly 仅请求 api、refresh_token 和 id 权限，分别用于 API 访问、保持连接和识别连接用户。

随后进入该连接的 Salesforce 页面，继续完成设置。新连接使用安全默认值启动同步：记录发送、回复、退信、退订和会议，不覆盖已有值的字段，仅在有人回复时创建 Lead。在原生同步推出前建立的连接默认关闭同步，需从概览开启。

可以同时连接沙盒和生产环境，两者为独立连接，设置互不影响。断开连接会立即在 Salesforce 撤销 Warmbly 令牌。

每个 Warmbly 联系人，在每个已连接组织中最多关联一条记录，按邮箱地址匹配：

• 同一地址同时存在 Contact 和 Lead 时，默认优先 Contact。如果组织优先处理 Leads，可将匹配 > 优先对象改为 Lead。
• 已转换的 Lead 不参与匹配。已关联 Lead 转换后，关联会跟随到转换形成的 Contact。
• 无匹配时，由创建时机决定：从不、对方回复或预约会议时（默认），或首次记录发送邮件时。退信、退订、打开或点击不会触发创建。创建为决定创建 Lead 还是 Contact。原生同步推出前建立的连接，仍沿用原创建或更新操作的行为创建 Contact，直到你修改。

新记录带入姓名、公司、电话、职位、所设的 Lead Source（潜在客户来源）（默认 Warmbly）以及初始 Lead Status（潜在客户状态）。缺少公司时使用邮箱域名，因为 Salesforce 的 Lead 要求公司。负责人可为连接用户、邮箱地址与发件邮箱匹配的 Salesforce 用户，或固定用户。开启运行分配规则后，由组织的潜在客户分配规则决定。仅发出提醒的重复规则不会阻止保存。

关联会在活动流入、打开联系人抽屉、导入，以及联系人页执行推送到 Salesforce时建立。

每个事件以已完成 Task 记录到 Lead 或 Contact，并在时间线上显示邮件图标：

打开和点击默认关闭，因为每次都会消耗 API 调用并增加时间线条目；邮件客户端预取本来也不会计为打开。

Contact 的 Task 会关联到所属 Account 最近活跃的未关闭 Opportunity（若存在），让商机复盘也能看到外联记录。Task 的负责人可为记录负责人、发件人的 Salesforce 用户或连接用户。如果 Lead 属于队列，则回退到连接用户，因为队列不能拥有 Task。

事件发生时即被记录，以最多 200 条一批写入，通常在一分钟内完成。发送只在邮件确实发出后记录，因此发送失败后重试也只出现一次。即使事件被上报两次，也只记录一次。关闭包含邮件文本后，仅记录主题和元数据。

对于尚未转换的 Lead，Warmbly 可以更新 Lead Status：

• 首次发信时，例如改为 Working - Contacted（跟进中 — 已联系）；
• 收到回复时，按判定意图更新：感兴趣、不感兴趣、提问、中立、外出或任意回复。外出自动回复仅在明确配置映射时改变 Lead 状态；
• 预约会议时。

开启状态不得倒退后，已经位于状态选项列表更后阶段的 Lead 会保持原状态。

拒收同步设为双向（默认）时：

• Warmbly 中的退订或垃圾邮件投诉，会设置记录的 Email Opt Out（拒绝接收邮件）（HasOptedOutOfEmail）；
• Salesforce 设置 Email Opt Out（拒绝接收邮件） 后，Warmbly 会将地址加入禁止发送名单并取消联系人订阅，所有营销活动都不再向其发信。此规则适用于字段变化、联系人首次关联到已拒收记录，以及导入时。

可限制为单向同步，或关闭。

Warmbly 每五分钟读取组织变更，更新已关联联系人的负责人、Lead Status、Account、转换和拒收状态。它还可以在联系人参与的每个活动中暂停外联，效果与成员手动暂停潜在客户相同：

• Lead 已转换；
• Lead 进入你选择的状态，例如 Qualified（已确认合格） 或 Unqualified（不合格）；
• Contact 所属 Account 出现新的未关闭 Opportunity，表明商机已经有人跟进。

暂停的潜在客户会在活动抽屉中显示“由 Salesforce 暂停”及原因，直到人工恢复。规则不会覆盖成员设置的暂停，而且每次变化只触发一次，因此恢复后不会被下一次拉取再次暂停。

字段映射按对象为每个字段列出一条规则：

Warmbly 字段包括名、姓、公司、电话、任意联系人自定义字段，以及五个可推送到自有自定义字段的只读互动值：最近营销活动、最近发信时间、最近回复时间、最近回复意图和外联状态。Salesforce 字段来自组织自己的字段列表；公式、汇总和自动编号字段只能读取。Contact 上的 Account Name（客户名称） 等关联字段也为只读。

“仅填充空白”不会写入 Warmbly 未读取过的字段，因此不会覆盖从未看到的值。默认规则双向补全姓名、电话和公司，不覆盖任一侧已有内容。

导入 > 新建导入可从以下来源导入人员：

• Lead 列表视图或 Contact 列表视图，沿用视图自己的筛选和范围。视图以连接用户运行，因此“My Leads”指该用户的 Leads；
• Salesforce Campaign（Salesforce 营销活动），读取各成员的 Lead，或已转换 Lead 对应的 Contact。

写入前，预览会显示人数和示例。可选择加入的 Warmbly 营销活动及标签。没有邮箱的人会被计数并跳过，后续拥有邮箱时再导入。如果拒收同步读取 Salesforce，已设置 Email Opt Out（拒绝接收邮件） 的人员会加入禁止发送名单，而非导入。导入的联系人与来源记录关联，来源标为 CRM 同步。

开启保持同步后，每 30 分钟重读列表，只导入新出现的人，避免下次运行覆盖团队成员在 Warmbly 中的修改。每次最多导入 10,000 人，其余在后续运行导入。

联系人抽屉和每个收件箱会话显示 Salesforce 卡片：Lead 或 Contact、负责人、Lead Status、Account、未关闭 Opportunity、最近的 Salesforce Tasks（Warmbly 自己创建的会标注）、拒收及转换标记，以及最近同步时间。在 Salesforce 中打开直达记录。尚不存在于 Salesforce 时，添加到 Salesforce可创建 Lead 或 Contact。立即同步刷新卡片并推送已映射字段。

• 概览显示连接健康状态、Warmbly 今日 API 调用与额度、组织整体每日用量、待处理及失败活动，以及最近拉取时间。
• 活动日志逐条列出事件和 Salesforce 原始错误文本，例如 REQUIRED_FIELD_MISSING。可选中行点击重试，或重试全部失败项。
• 临时错误使用退避机制，最多尝试六次。Salesforce 永久拒绝的记录标为失败，只有你要求时才重试。

API 调用额度

Warmbly 会限制自身每日调用，默认上限为组织每日配额的五分之一；组织整体用量超过 95% 时暂停后台工作。达到任一限制后，待处理活动等待下一个 UTC 日期，不与其他工具争抢额度。可将每日 API 额度设为固定值修改上限。打开联系人卡片不会被额度限制阻止。

重新连接

Salesforce 结束会话时，例如密码重置、应用被撤销或用户停用，连接显示重新连接，活动等待处理。数据不会丢失，重新连接后会继续记录。

自动化流程中的创建或更新 Salesforce 记录操作，与同步功能使用相同的匹配、创建和字段规则，因此两者不会对人员身份作出不同判断。

已保存的导入任务随工作区导出的自动化数据组迁移。联系人与记录的关联、活动日志和拉取进度不会迁移：目标实例首次同步时按邮箱重新关联，已写入的 Tasks 则保留在 Salesforce。开始同步前，需在目标实例重新连接 Salesforce。

自托管实例需要自己的 Salesforce 应用，类型取决于要连接多少个 Salesforce 组织：

• 仅连接自己的组织。 在该组织创建 External Client App（外部客户端应用）。Salesforce 默认将此类应用设为 Local（本地），只能在创建它的组织内使用，因此沙盒需要自己的应用，或在由原组织创建、刷新沙盒时获得副本。
• 连接多个组织，或不由你管理的组织。 使用任意组织均可授权的 Connected App（已连接应用）。自 Spring '26 起，创建前需请 Salesforce Support 为组织启用，再到 Setup > External Client Apps > Settings（设置 > 外部客户端应用 > 设置） 开启 Allow creation of connected apps（允许创建已连接应用）。打包的 External Client App 也可以，但每个组织都必须先安装你的包才能连接。

无论创建哪种应用，都需配置：

• 回调 URL：使用 INTEGRATIONS_OAUTH_REDIRECT_URL；若未设置，则使用 BACKEND_PUBLIC_URL，再不行使用 API_PUBLIC_URL，并追加 /integrations/oauth/callback。必须完全一致，包括协议，且不能有尾部斜杠。
• OAuth 权限：Manage user data via APIs (api)（通过 API 管理用户数据）、Perform requests at any time (refresh_token, offline_access)（随时执行请求） 和 Access the identity URL service (id, profile, email, address, phone)（访问身份 URL 服务）。
• 开启 Require PKCE（要求 PKCE） 和 Web Server Flow（Web 服务器流程），并要求客户端密钥。
• 刷新令牌设置为 valid until revoked，即撤销前持续有效。

将 consumer key 和 secret 分别填入 SALESFORCE_OAUTH_CLIENT_ID 和 SALESFORCE_OAUTH_CLIENT_SECRET，参见配置，然后重启后端。Salesforce 可能需要几分钟激活新应用，此前连接会报 invalid_client_id。