> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HubSpot
> 使用原生 OneSignal 集成，通过 HubSpot 工作流自动化推送通知、电子邮件、短信和应用内消息。
## 概览
OneSignal HubSpot 集成通过原生工作流操作将您的 HubSpot CRM 连接到 OneSignal——无需第三方中间件。您可以：
* **发送消息** — 从 HubSpot 工作流触发推送通知、电子邮件和短信
* **创建用户** — 将 HubSpot 联系人同步到 OneSignal，包含电子邮件和短信订阅
* **管理标签** — 根据 HubSpot 联系人属性设置或删除 OneSignal [标签](./add-user-data-tags)
* **定向应用内消息** — 使用 HubSpot 设置的标签构建分段，控制应用内消息的推送
对于 A/B 测试、智能传递、限流和重新定位等功能，请直接使用 OneSignal 控制台或 API 配合 HubSpot。
阅读[使用 HubSpot 与 OneSignal 集成的四种方式](https://onesignal.com/blog/four-ways-to-use-the-onesignal-integration-with-hubspot-to-boost-engagement-across-channels/)了解实际案例。
***
## 前提条件
* HubSpot 超级管理员角色或[应用市场权限](https://knowledge.hubspot.com/settings/hubspot-user-permissions-guide#admin)
* [付费 OneSignal 计划](https://onesignal.com/pricing)（免费计划不可用）
HubSpot 于 2024 年 12 月弃用了原来的第三方 OneSignal 应用。OneSignal 现在提供具有扩展功能的自有 HubSpot 应用。如果您使用过之前的集成，请参阅下面的迁移步骤。
**安装新集成**
按照下面[将 HubSpot 连接到 OneSignal](#connect-hubspot-to-onesignal) 中的说明，从 OneSignal 控制台的 **Data > Integrations** 激活 HubSpot 集成。
**迁移您的工作流**
我们建议在替换现有工作流中的操作之前，先创建新工作流来测试新集成。
1. **克隆工作流** — 在 HubSpot **工作流**页面，点击现有工作流旁边的**克隆**。
2. **删除触发器** — 在克隆的工作流中，删除所有注册触发器，以防发布时自动触发。
3. **替换旧版操作** — 删除每个旧版 OneSignal 操作并用新版本替换。如果两个应用都已安装，旧版应用显示"Built by HubSpot"——使用不显示该文字的那个。
4. **用单个联系人测试** — 保存并发布工作流，然后手动注册一个测试联系人。检查注册历史记录以验证操作是否成功完成。
5. **替换或更新** — 确认工作流正常运行后，用克隆替换原始工作流，或将相同更改应用于原始工作流。
如果迁移过程中遇到错误，请联系 `support@onesignal.com`。
***
## 将 HubSpot 连接到 OneSignal
### 激活集成
在 OneSignal 中，转到 **Data > Integrations > Catalog**，选择 **HubSpot**。
点击 **Settings > Authenticate**，然后选择您的 HubSpot 账户并登录。
每个 OneSignal 应用只能连接一个 HubSpot 账户。如果您有测试环境，可以为测试设置另一个 OneSignal 应用。
同意条款并选择 **Connect app** 后，您将被重定向到 OneSignal。打开新连接的 HubSpot 账户以确认连接。
### 通过 External ID 匹配用户
要将 HubSpot 联系人与 OneSignal 用户关联，请将 OneSignal 中的 [External ID](./users) 设置为与 HubSpot 中某个唯一属性匹配的值（例如用户 ID 或电子邮件地址）。
在您的应用或网站中使用 SDK `login` 方法设置 External ID。选择在您的应用和 HubSpot 中都容易获取的属性，以确保匹配可靠。
有关身份和订阅管理的详细信息，请参阅[用户](./users)和[订阅](./subscriptions)。
### 创建 HubSpot 工作流
在 HubSpot 中，转到 **Automation > Workflows**，点击 **Create workflow**。选择 **Contact-based** 并配置注册触发器。
要添加 OneSignal 操作，在工作流编辑器中点击 **+** 并搜索"OneSignal"。
每个 OneSignal 操作都需要两个字段：
* **OneSignal App** — 您在设置过程中连接的应用
* **External ID** — 与 OneSignal 中 External ID 匹配的 HubSpot 联系人属性
***
## OneSignal 操作
### 从 HubSpot 创建 OneSignal 用户
**创建用户**操作在联系人通过工作流时在 OneSignal 中创建[用户](./users)。使用此操作可在添加新联系人时保持 OneSignal 和 HubSpot 同步。
如果设置了以下 HubSpot 属性，OneSignal 会自动创建相应的[订阅](./subscriptions)：
* **电子邮件** → 在 OneSignal 中创建电子邮件订阅
* **电话号码** → 在 OneSignal 中创建短信订阅
您也可以在"创建用户"节点中设置 External ID 和标签。
如果您的 OneSignal 应用启用了[双重选择加入](./sms-opt-in-and-collection#promotional-double-opt-in-form)，新的短信订阅将自动收到选择加入消息。您可以在"创建用户"节点中禁用此功能——将创建短信订阅，但用户在单独选择加入之前不会被订阅。
***
### 从 HubSpot 编辑 OneSignal 标签
**编辑标签**操作在匹配的 OneSignal 用户上设置或删除[标签](./add-user-data-tags)。标签支持[消息个性化](./message-personalization)和[分段](./segmentation)，也是[从 HubSpot 定向应用内消息](#send-in-app-messages-with-hubspot)的机制。
#### 设置标签
在标签字段中输入 JSON 对象：
```json theme={null}
{ "welcome": "1", "name": "" }
```
您可以使用工作流编辑器中 HubSpot 的属性令牌插入器，将任意 HubSpot 联系人属性注入为标签值。例如，将用户名作为标签添加，以便在 OneSignal 中个性化消息。
#### 删除标签
将值设置为空字符串以删除标签：
```json theme={null}
{ "old_tag": "" }
```
如果标签在用户上不存在，则会被忽略。
***
### 从 HubSpot 工作流发送消息
**发送通知**操作向匹配的 OneSignal 用户发送推送通知、电子邮件或短信。
通过 **OneSignal External ID** 而非电子邮件匹配用户。电子邮件匹配是使用 `addEmail` SDK 方法设置电子邮件的客户的旧版选项。
**使用模板**
选择在 OneSignal 控制台或 API 中创建的预定义[模板](./templates)。模板支持推送通知、电子邮件和短信。
**使用表单字段**
如果不选择模板，可以直接在工作流操作中使用标题、副标题、消息、图像 URL 和启动 URL 字段编写推送通知。电子邮件和短信只能通过模板使用。
表单字段选项允许您注入 HubSpot 联系人属性（例如 `First Name`）来个性化通知内容。
***
#### 使用 HubSpot 发送应用内消息
应用内消息无法直接从 HubSpot 工作流发送。请改为使用 HubSpot 为用户打标签，然后在 OneSignal 中用基于分段的应用内消息定向这些用户。
在您的 HubSpot 工作流中，使用[编辑标签](#edit-onesignal-tags-from-hubspot)操作为联系人设置标签。例如：`{ "hubspot_campaign": "spring_promo" }`。
在 OneSignal 控制台中，转到 **Audience > Segments** 并点击 **New Segment**。添加与 HubSpot 设置的标签键和值匹配的**用户标签**过滤器（例如，`hubspot_campaign` 为 `spring_promo`）。
转到 **Messages > In-App** 并创建新的应用内消息。在**受众**下，选择**显示给特定分段**并选择您创建的分段。
当用户通过 HubSpot 工作流并收到标签时，他们会立即被添加到分段中。
标签本身不会触发应用内消息。如果在用户正在使用应用时设置标签，应用内消息不会显示，直到下一个会话（应用在后台超过 30 秒后开始新会话）。
可用触发器：
* **应用打开时** — 用户下次打开应用时显示
* **会话时长** — 在会话内指定秒数后显示
* **距上次应用内消息的时间** — 防止连续消息
* **程序化** — 使用 OneSignal SDK 从应用代码触发
有关使用 AND/OR 运算符组合触发器的详细信息，请参阅[应用内消息触发器](./iam-triggers)。
***
## 常见工作流模式
HubSpot 工作流将**注册触发器**（启动工作流的事件）与 **OneSignal 操作**（在 OneSignal 中对用户执行的操作）相结合。以下是常见使用场景的推荐模式。
以下每个工作流模式均假设您已[将 HubSpot 连接到 OneSignal](#connect-hubspot-to-onesignal)并[通过 External ID 匹配用户](#match-users-with-external-id)。
### 欢迎与引导
在新用户注册时发送欢迎消息，并为引导应用内消息打标签。
| 步骤 | 类型 | 配置 |
| --------- | --------------- | -------------------------------------------------------------------------------- |
| **注册触发器** | HubSpot | 联系人属性`成为客户日期`已知 |
| **操作 1** | OneSignal: 创建用户 | 将 External ID 设置为与您应用匹配的 HubSpot 联系人属性（例如用户 ID 或电子邮件地址） |
| **操作 2** | OneSignal: 编辑标签 | `{ "onboarding": "active", "name": "" }` — 为 name 值插入 HubSpot 名字属性令牌 |
| **操作 3** | OneSignal: 发送通知 | 使用欢迎推送模板，或内联编写个性化问候语 |
将此与定向 `onboarding` = `active` 分段的[应用内消息](#send-in-app-messages-with-hubspot)配合使用，在首次启动时引导新用户了解您的应用。
### 重新激活
联系近期未访问您应用的用户。
| 步骤 | 类型 | 配置 |
| --------- | --------------- | ------------------------------ |
| **注册触发器** | HubSpot | 联系人属性`最近活动日期`超过 14 天前 |
| **操作 1** | OneSignal: 发送通知 | 使用重新激活推送模板（例如，"我们想念您——这是最新消息"） |
| **延迟** | HubSpot: 等待 3 天 | — |
| **条件分支** | HubSpot | 检查联系人是否在注册后访问了您的网站 |
| **是分支** | OneSignal: 编辑标签 | `{ "reengaged": "true" }` |
| **否分支** | OneSignal: 发送通知 | 使用激励力度更强的电子邮件模板 |
### 生命周期阶段变更
将 HubSpot 中的生命周期阶段变化同步到 OneSignal 标签，以便定向不同用户分段。
| 步骤 | 类型 | 配置 |
| --------- | --------------- | ---------------------------------------------------------------------- |
| **注册触发器** | HubSpot | 联系人属性`生命周期阶段`变为任意值 |
| **操作 1** | OneSignal: 编辑标签 | `{ "lifecycle_stage": "" }` — 为值插入 HubSpot 生命周期阶段属性令牌 |
| **条件分支** | HubSpot | 检查生命周期阶段是否为`客户` |
| **是分支** | OneSignal: 发送通知 | 使用"欢迎加入大家庭"推送或电子邮件模板 |
### 成交 / 购后
交易完成后触发感谢消息并为追加销售活动打标签。
| 步骤 | 类型 | 配置 |
| --------- | --------------- | -------------------------------------------------------------------------- |
| **注册触发器** | HubSpot | 交易属性`交易阶段` = `已赢得` |
| **操作 1** | OneSignal: 编辑标签 | `{ "customer": "true", "deal_value": "" }` — 为值插入 HubSpot 交易金额属性令牌 |
| **操作 2** | OneSignal: 发送通知 | 使用感谢电子邮件模板 |
| **延迟** | HubSpot: 等待 7 天 | — |
| **操作 3** | OneSignal: 发送通知 | 使用追加/交叉销售推送模板 |
基于交易的工作流需要 HubSpot 中的**交易型**工作流类型。使用关联联系人的 External ID 匹配 OneSignal 用户。
### 通过应用内消息的促销活动
使用 HubSpot 列表或表单触发的应用内消息定向特定受众。
| 步骤 | 类型 | 配置 |
| --------- | --------------- | ---------------------------- |
| **注册触发器** | HubSpot | 联系人成为静态或活跃列表的成员（例如，"春季特卖资格"） |
| **操作 1** | OneSignal: 编辑标签 | `{ "promo": "spring_2025" }` |
然后按照[使用 HubSpot 发送应用内消息](#send-in-app-messages-with-hubspot)的步骤，创建匹配 `promo` = `spring_2025` 的 OneSignal 分段并为该分段配置应用内消息。
要在活动结束后将用户从活动中移除，创建第二个删除标签的工作流：
| 步骤 | 类型 | 配置 |
| --------- | --------------- | ----------------- |
| **注册触发器** | HubSpot | 基于日期，设置为活动结束日期 |
| **操作 1** | OneSignal: 编辑标签 | `{ "promo": "" }` |
***
## 故障排除
### HubSpot 中工作流操作显示"失败"
1. **检查错误消息** — 在 HubSpot 工作流注册历史记录中展开失败的操作。错误消息通常指出原因（例如，"未找到用户"、"无效的应用 ID"）。
2. **验证 External ID** — 确认用作 External ID 的 HubSpot 联系人属性与 OneSignal 中的用户匹配。在 **OneSignal > Audience > Users** 中通过 External ID 搜索用户档案。
3. **确认集成已激活** — 转到 **OneSignal > Data > Integrations > HubSpot**，验证连接状态为活跃。
### 消息已发送但用户未收到
1. **检查订阅** — 用户必须对您发送的渠道（推送、电子邮件或短信）有活跃订阅。在 OneSignal 的用户档案中的**订阅**下验证。
2. **检查分段成员资格** — 如果您使用带有分段定向的模板，确认用户属于目标分段。
3. **查看消息报告** — 在 OneSignal 控制台中，转到**消息**，找到消息，检查其投递报告，查看消息是否已投递、被丢弃或出错。
### 标签未出现在 OneSignal 用户上
1. **验证 External ID 匹配** — 如果工作流中的 External ID 与现有 OneSignal 用户不匹配，编辑标签操作将静默失败。在编辑标签之前先使用**创建用户**操作，确保用户存在。
2. **检查 JSON 格式** — 标签必须是有效的 JSON 对象。常见错误包括键或值缺少引号、末尾逗号，或使用单引号而非双引号。
3. **检查空值** — 将标签值设置为 `""` 会删除标签。验证注入的 HubSpot 联系人属性不为空。
### 应用内消息未显示
请参阅下方常见问题中的[为什么设置标签后应用内消息没有显示？](#why-didnt-my-in-app-message-display-after-the-tag-was-set)。
***
## 常见问题
### HubSpot 和 OneSignal 之间共享哪些数据？
| HubSpot | 方向 | OneSignal | 描述 |
| ------- | -- | -------------- | -------------------------------------------------------------------------------------- |
| 联系人属性 | → | External ID、标签 | HubSpot 联系人数据通过 [External ID](./users) 和[标签](./add-user-data-tags) 匹配并丰富 OneSignal 用户。 |
| 工作流 | ← | 消息模板 | OneSignal [模板](./templates)可在 HubSpot 工作流操作中选择。 |
集成不会自动将 HubSpot 列表、交易或公司记录同步到 OneSignal。使用工作流操作显式传递您需要的数据。
### 如果 External ID 与 OneSignal 用户不匹配会发生什么？
**发送通知**和**编辑标签**操作将静默失败——不发送消息，不设置标签。始终在工作流中的其他 OneSignal 操作之前放置**创建用户**操作，以确保用户存在于 OneSignal 中。
### 我可以使用 HubSpot 列表定向 OneSignal 分段吗？
不能直接使用。HubSpot 列表和 OneSignal 分段是独立的系统。要连接它们，创建一个工作流，从 HubSpot 列表注册联系人，并使用**编辑标签**操作设置标签。然后基于该标签构建 OneSignal 分段。参见[通过应用内消息的促销活动](#promotional-campaign-via-in-app-message)了解示例。
### 我可以从 HubSpot 发送哪些 OneSignal 渠道？
推送通知可以使用模板或表单字段发送。电子邮件和短信只能使用在 OneSignal 中创建的[模板](./templates)发送。应用内消息无法从 HubSpot 工作流发送——请改用[标签和分段模式](#send-in-app-messages-with-hubspot)。
### 为什么设置标签后应用内消息没有显示？
仅靠标签无法触发应用内消息。标签将用户添加到分段，但应用内消息仍需要**触发器**才能显示。如果在用户正在使用应用时设置标签，消息不会出现，直到下一个会话（后台超过 30 秒）。将应用内消息触发器设置为**应用打开时**以获得最可靠的行为。有关所有触发器选项，请参阅[应用内消息触发器](./iam-triggers)。
### 我可以使用 HubSpot Webhook 直接调用 OneSignal API 吗？
可以。HubSpot 的**自定义代码**工作流操作允许您向外部 API 发出 HTTP 请求。您可以调用 [OneSignal REST API](/reference/create-notification) 在原生集成之外发送消息、创建用户或更新标签。这对于原生操作不涵盖的用例（例如向分段而非个人用户发送）很有用。
### 我可以将 OneSignal 消息事件发回 HubSpot 吗？
可以。使用[事件流](./event-streams)将 OneSignal 消息事件（已发送、已点击等）导出到 Webhook 端点。您可以将这些事件路由到 HubSpot 的[自定义事件 API](https://developers.hubspot.com/docs/api/analytics/events)，或使用中间件服务根据 OneSignal 参与数据更新 HubSpot 联系人属性。
### 我可以从 HubSpot 触发 OneSignal Journey 吗？
将 HubSpot 用户加入 OneSignal [Journey](./journeys-overview) 有两种选项：
1. **标签** — 使用[编辑标签](#edit-onesignal-tags-from-hubspot)操作为用户设置标签。在 OneSignal 中基于该标签创建分段，并将该分段用作 Journey 入口条件。
2. **自定义事件** — 使用 HubSpot 的**自定义代码**操作调用 [OneSignal 自定义事件 API](/reference/create-custom-events)，可用作 Journey 入口触发器。
### 我可以从 HubSpot 向 OneSignal 发送自定义事件吗？
不能通过原生工作流操作实现。原生集成支持创建用户、编辑标签和发送通知。要发送自定义事件，请使用 HubSpot 的**自定义代码**操作直接调用 [OneSignal 自定义事件 API](/reference/create-custom-events)。
### 哪些 HubSpot 注册触发器可与 OneSignal 配合使用？
任何 HubSpot 注册触发器均可使用——OneSignal 操作是标准工作流操作，无论联系人如何注册都会执行。常见触发器包括：
* **联系人属性变更**（生命周期阶段、潜在客户状态、最近活动日期）
* **表单提交**（注册表单、演示请求、活动注册）
* **列表成员资格**（添加到静态或活跃列表）
* **交易阶段变更**（管道进展、已赢得/已输掉）
* **基于日期**（定时活动、事件后的时间）
* **手动注册**（用于一次性发送或测试）
### 上线前如何测试工作流？
1. 创建工作流并删除所有自动注册触发器
2. 保存并发布工作流
3. 手动注册单个测试联系人
4. 检查 HubSpot 中的注册历史记录，查看操作成功/失败情况
5. 在 OneSignal 控制台中验证用户、标签或消息
6. 确认后，添加注册触发器并重新发布
***
为用户添加自定义属性，用于个性化和分段。
为推送、电子邮件和短信创建可复用的消息模板。
构建由用户行为触发的自动化多渠道消息流程。
通过 Webhook 将实时消息事件导出到外部平台。
根据标签、行为和用户属性构建受众分段。
控制应用内消息向用户显示的时间和方式。