概览
OneSignal HubSpot 集成通过原生工作流操作将您的 HubSpot CRM 连接到 OneSignal——无需第三方中间件。您可以：- 发送消息 — 从 HubSpot 工作流触发推送通知、电子邮件和短信
- 创建用户 — 将 HubSpot 联系人同步到 OneSignal，包含电子邮件和短信订阅
- 管理标签 — 根据 HubSpot 联系人属性设置或删除 OneSignal 标签
- 定向应用内消息 — 使用 HubSpot 设置的标签构建分段，控制应用内消息的推送
前提条件
- HubSpot 超级管理员角色或应用市场权限
- 付费 OneSignal 计划（免费计划不可用）
HubSpot 于 2024 年 12 月弃用了原来的第三方 OneSignal 应用。OneSignal 现在提供具有扩展功能的自有 HubSpot 应用。如果您使用过之前的集成，请参阅下面的迁移步骤。
从旧版 HubSpot 集成迁移
从旧版 HubSpot 集成迁移
安装新集成按照下面将 HubSpot 连接到 OneSignal 中的说明，从 OneSignal 控制台的 Data > Integrations 激活 HubSpot 集成。迁移您的工作流我们建议在替换现有工作流中的操作之前，先创建新工作流来测试新集成。
- 克隆工作流 — 在 HubSpot 工作流页面，点击现有工作流旁边的克隆。
- 删除触发器 — 在克隆的工作流中，删除所有注册触发器，以防发布时自动触发。
- 替换旧版操作 — 删除每个旧版 OneSignal 操作并用新版本替换。如果两个应用都已安装，旧版应用显示”Built by HubSpot”——使用不显示该文字的那个。
- 用单个联系人测试 — 保存并发布工作流，然后手动注册一个测试联系人。检查注册历史记录以验证操作是否成功完成。
- 替换或更新 — 确认工作流正常运行后，用克隆替换原始工作流，或将相同更改应用于原始工作流。
support@onesignal.com。将 HubSpot 连接到 OneSignal
激活集成
在 OneSignal 中，转到 Data > Integrations > Catalog，选择 HubSpot。
通过 External ID 匹配用户
要将 HubSpot 联系人与 OneSignal 用户关联，请将 OneSignal 中的 External ID 设置为与 HubSpot 中某个唯一属性匹配的值（例如用户 ID 或电子邮件地址）。 在您的应用或网站中使用 SDKlogin 方法设置 External ID。选择在您的应用和 HubSpot 中都容易获取的属性，以确保匹配可靠。
创建 HubSpot 工作流
在 HubSpot 中，转到 Automation > Workflows，点击 Create workflow。选择 Contact-based 并配置注册触发器。 要添加 OneSignal 操作，在工作流编辑器中点击 + 并搜索”OneSignal”。
- OneSignal App — 您在设置过程中连接的应用
- External ID — 与 OneSignal 中 External ID 匹配的 HubSpot 联系人属性
OneSignal 操作
从 HubSpot 创建 OneSignal 用户
创建用户操作在联系人通过工作流时在 OneSignal 中创建用户。使用此操作可在添加新联系人时保持 OneSignal 和 HubSpot 同步。 如果设置了以下 HubSpot 属性，OneSignal 会自动创建相应的订阅：- 电子邮件 → 在 OneSignal 中创建电子邮件订阅
- 电话号码 → 在 OneSignal 中创建短信订阅
从 HubSpot 编辑 OneSignal 标签
编辑标签操作在匹配的 OneSignal 用户上设置或删除标签。标签支持消息个性化和分段，也是从 HubSpot 定向应用内消息的机制。设置标签
在标签字段中输入 JSON 对象：删除标签
将值设置为空字符串以删除标签：
从 HubSpot 工作流发送消息
发送通知操作向匹配的 OneSignal 用户发送推送通知、电子邮件或短信。
First Name）来个性化通知内容。
使用 HubSpot 发送应用内消息
应用内消息无法直接从 HubSpot 工作流发送。请改为使用 HubSpot 为用户打标签，然后在 OneSignal 中用基于分段的应用内消息定向这些用户。从 HubSpot 为用户打标签
在您的 HubSpot 工作流中，使用编辑标签操作为联系人设置标签。例如：
{ "hubspot_campaign": "spring_promo" }。在 OneSignal 中创建分段
在 OneSignal 控制台中，转到 Audience > Segments 并点击 New Segment。添加与 HubSpot 设置的标签键和值匹配的用户标签过滤器（例如，
hubspot_campaign 为 spring_promo）。创建应用内消息
转到 Messages > In-App 并创建新的应用内消息。在受众下，选择显示给特定分段并选择您创建的分段。当用户通过 HubSpot 工作流并收到标签时，他们会立即被添加到分段中。
配置触发器
标签本身不会触发应用内消息。如果在用户正在使用应用时设置标签，应用内消息不会显示，直到下一个会话（应用在后台超过 30 秒后开始新会话）。可用触发器：
- 应用打开时 — 用户下次打开应用时显示
- 会话时长 — 在会话内指定秒数后显示
- 距上次应用内消息的时间 — 防止连续消息
- 程序化 — 使用 OneSignal SDK 从应用代码触发
常见工作流模式
HubSpot 工作流将注册触发器（启动工作流的事件）与 OneSignal 操作（在 OneSignal 中对用户执行的操作）相结合。以下是常见使用场景的推荐模式。以下每个工作流模式均假设您已将 HubSpot 连接到 OneSignal并通过 External ID 匹配用户。
欢迎与引导
在新用户注册时发送欢迎消息，并为引导应用内消息打标签。| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 联系人属性成为客户日期已知 |
| 操作 1 | OneSignal: 创建用户 | 将 External ID 设置为与您应用匹配的 HubSpot 联系人属性（例如用户 ID 或电子邮件地址） |
| 操作 2 | OneSignal: 编辑标签 | { "onboarding": "active", "name": "<First Name>" } — 为 name 值插入 HubSpot 名字属性令牌 |
| 操作 3 | OneSignal: 发送通知 | 使用欢迎推送模板，或内联编写个性化问候语 |
重新激活
联系近期未访问您应用的用户。| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 联系人属性最近活动日期超过 14 天前 |
| 操作 1 | OneSignal: 发送通知 | 使用重新激活推送模板（例如，“我们想念您——这是最新消息”） |
| 延迟 | HubSpot: 等待 3 天 | — |
| 条件分支 | HubSpot | 检查联系人是否在注册后访问了您的网站 |
| 是分支 | OneSignal: 编辑标签 | { "reengaged": "true" } |
| 否分支 | OneSignal: 发送通知 | 使用激励力度更强的电子邮件模板 |
生命周期阶段变更
将 HubSpot 中的生命周期阶段变化同步到 OneSignal 标签，以便定向不同用户分段。| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 联系人属性生命周期阶段变为任意值 |
| 操作 1 | OneSignal: 编辑标签 | { "lifecycle_stage": "<Lifecycle Stage>" } — 为值插入 HubSpot 生命周期阶段属性令牌 |
| 条件分支 | HubSpot | 检查生命周期阶段是否为客户 |
| 是分支 | OneSignal: 发送通知 | 使用”欢迎加入大家庭”推送或电子邮件模板 |
成交 / 购后
交易完成后触发感谢消息并为追加销售活动打标签。| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 交易属性交易阶段 = 已赢得 |
| 操作 1 | OneSignal: 编辑标签 | { "customer": "true", "deal_value": "<Amount>" } — 为值插入 HubSpot 交易金额属性令牌 |
| 操作 2 | OneSignal: 发送通知 | 使用感谢电子邮件模板 |
| 延迟 | HubSpot: 等待 7 天 | — |
| 操作 3 | OneSignal: 发送通知 | 使用追加/交叉销售推送模板 |
基于交易的工作流需要 HubSpot 中的交易型工作流类型。使用关联联系人的 External ID 匹配 OneSignal 用户。
通过应用内消息的促销活动
使用 HubSpot 列表或表单触发的应用内消息定向特定受众。| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 联系人成为静态或活跃列表的成员（例如，“春季特卖资格”） |
| 操作 1 | OneSignal: 编辑标签 | { "promo": "spring_2025" } |
promo = spring_2025 的 OneSignal 分段并为该分段配置应用内消息。
要在活动结束后将用户从活动中移除，创建第二个删除标签的工作流：
| 步骤 | 类型 | 配置 |
|---|---|---|
| 注册触发器 | HubSpot | 基于日期，设置为活动结束日期 |
| 操作 1 | OneSignal: 编辑标签 | { "promo": "" } |
故障排除
HubSpot 中工作流操作显示”失败”
- 检查错误消息 — 在 HubSpot 工作流注册历史记录中展开失败的操作。错误消息通常指出原因（例如，“未找到用户”、“无效的应用 ID”）。
- 验证 External ID — 确认用作 External ID 的 HubSpot 联系人属性与 OneSignal 中的用户匹配。在 OneSignal > Audience > Users 中通过 External ID 搜索用户档案。
- 确认集成已激活 — 转到 OneSignal > Data > Integrations > HubSpot，验证连接状态为活跃。
消息已发送但用户未收到
- 检查订阅 — 用户必须对您发送的渠道（推送、电子邮件或短信）有活跃订阅。在 OneSignal 的用户档案中的订阅下验证。
- 检查分段成员资格 — 如果您使用带有分段定向的模板，确认用户属于目标分段。
- 查看消息报告 — 在 OneSignal 控制台中，转到消息，找到消息，检查其投递报告，查看消息是否已投递、被丢弃或出错。
标签未出现在 OneSignal 用户上
- 验证 External ID 匹配 — 如果工作流中的 External ID 与现有 OneSignal 用户不匹配，编辑标签操作将静默失败。在编辑标签之前先使用创建用户操作，确保用户存在。
- 检查 JSON 格式 — 标签必须是有效的 JSON 对象。常见错误包括键或值缺少引号、末尾逗号，或使用单引号而非双引号。
- 检查空值 — 将标签值设置为
""会删除标签。验证注入的 HubSpot 联系人属性不为空。
应用内消息未显示
请参阅下方常见问题中的为什么设置标签后应用内消息没有显示？。常见问题
HubSpot 和 OneSignal 之间共享哪些数据？
| HubSpot | 方向 | OneSignal | 描述 |
|---|---|---|---|
| 联系人属性 | → | External ID、标签 | HubSpot 联系人数据通过 External ID 和标签 匹配并丰富 OneSignal 用户。 |
| 工作流 | ← | 消息模板 | OneSignal 模板可在 HubSpot 工作流操作中选择。 |
如果 External ID 与 OneSignal 用户不匹配会发生什么？
发送通知和编辑标签操作将静默失败——不发送消息，不设置标签。始终在工作流中的其他 OneSignal 操作之前放置创建用户操作，以确保用户存在于 OneSignal 中。我可以使用 HubSpot 列表定向 OneSignal 分段吗？
不能直接使用。HubSpot 列表和 OneSignal 分段是独立的系统。要连接它们，创建一个工作流，从 HubSpot 列表注册联系人，并使用编辑标签操作设置标签。然后基于该标签构建 OneSignal 分段。参见通过应用内消息的促销活动了解示例。我可以从 HubSpot 发送哪些 OneSignal 渠道？
推送通知可以使用模板或表单字段发送。电子邮件和短信只能使用在 OneSignal 中创建的模板发送。应用内消息无法从 HubSpot 工作流发送——请改用标签和分段模式。为什么设置标签后应用内消息没有显示？
仅靠标签无法触发应用内消息。标签将用户添加到分段，但应用内消息仍需要触发器才能显示。如果在用户正在使用应用时设置标签，消息不会出现，直到下一个会话（后台超过 30 秒）。将应用内消息触发器设置为应用打开时以获得最可靠的行为。有关所有触发器选项，请参阅应用内消息触发器。我可以使用 HubSpot Webhook 直接调用 OneSignal API 吗？
可以。HubSpot 的自定义代码工作流操作允许您向外部 API 发出 HTTP 请求。您可以调用 OneSignal REST API 在原生集成之外发送消息、创建用户或更新标签。这对于原生操作不涵盖的用例（例如向分段而非个人用户发送）很有用。我可以将 OneSignal 消息事件发回 HubSpot 吗？
可以。使用事件流将 OneSignal 消息事件（已发送、已点击等）导出到 Webhook 端点。您可以将这些事件路由到 HubSpot 的自定义事件 API，或使用中间件服务根据 OneSignal 参与数据更新 HubSpot 联系人属性。我可以从 HubSpot 触发 OneSignal Journey 吗？
将 HubSpot 用户加入 OneSignal Journey 有两种选项：- 标签 — 使用编辑标签操作为用户设置标签。在 OneSignal 中基于该标签创建分段，并将该分段用作 Journey 入口条件。
- 自定义事件 — 使用 HubSpot 的自定义代码操作调用 OneSignal 自定义事件 API，可用作 Journey 入口触发器。
我可以从 HubSpot 向 OneSignal 发送自定义事件吗？
不能通过原生工作流操作实现。原生集成支持创建用户、编辑标签和发送通知。要发送自定义事件，请使用 HubSpot 的自定义代码操作直接调用 OneSignal 自定义事件 API。哪些 HubSpot 注册触发器可与 OneSignal 配合使用？
任何 HubSpot 注册触发器均可使用——OneSignal 操作是标准工作流操作，无论联系人如何注册都会执行。常见触发器包括：- 联系人属性变更（生命周期阶段、潜在客户状态、最近活动日期）
- 表单提交（注册表单、演示请求、活动注册）
- 列表成员资格（添加到静态或活跃列表）
- 交易阶段变更（管道进展、已赢得/已输掉）
- 基于日期（定时活动、事件后的时间）
- 手动注册（用于一次性发送或测试）
上线前如何测试工作流？
- 创建工作流并删除所有自动注册触发器
- 保存并发布工作流
- 手动注册单个测试联系人
- 检查 HubSpot 中的注册历史记录，查看操作成功/失败情况
- 在 OneSignal 控制台中验证用户、标签或消息
- 确认后，添加注册触发器并重新发布