# GoHighLevel (GHL) 集成

已经在通过 GoHighLevel (GHL) 管理您的业务了吗？此集成允许您在现有的 GHL 设置之上添加 <span data-t="appName">Your AI Connector</span> 的 AI 驱动消息功能。进入 GHL 的消息会被转发到 <span data-t="appName">Your AI Connector</span> 进行 AI 处理，来自 <span data-t="appName">Your AI Connector</span> 的回复会通过 GHL 以原始渠道发送回给客户。

> 使用其他 CRM？它不需要专门的屏幕即可与 <span data-t="appName">Your AI Connector</span> 配合使用：请参阅 [连接未列出的工具](connecting-other-tools.md) 以了解自定义函数、API 和 Webhook。

这意味着您可以继续将 GHL 作为主要中心，同时让 AI 处理由 AI 驱动的对话。

::: note
**注意：** 这是一个技术性较强的集成，涉及设置自动化工作流以及使用 Webhook（应用程序间的自动通知）和 API 调用来连接系统。如果您对此不熟悉，建议将此页面交给开发人员或精通技术的团队成员处理。
:::


---

## 前置条件

- 一个活跃的 **<span data-t="appName">Your AI Connector</span> 账户**，并准备好您的 API 密钥（可在 **Settings → Integrations → API Key** 中找到）。API 密钥是一个唯一代码，允许 GHL 与您的账户进行安全通信。
- 一个拥有创建工作流和管理 Webhook（系统间的自动通知）权限的 **GoHighLevel 账户**。

---

## 工作原理

| 方向 | 处理过程 |
|---|---|
| **GHL 到 <span data-t="appName">Your AI Connector</span>** | 客户通过 GHL 中的短信、电子邮件、Messenger、Instagram 或实时聊天给您发送消息。工作流会自动将该消息转发给 <span data-t="appName">Your AI Connector</span>。<span data-t="appName">Your AI Connector</span> 会对其进行处理（AI 回复、打标签等）。 |
| **<span data-t="appName">Your AI Connector</span> 到 GHL** | 当 <span data-t="appName">Your AI Connector</span> 发送回复（手动或通过 AI）时，它会自动通知 GHL。GHL 中的工作流会找到该联系人并通过正确的渠道发送回复。 |

---

## 工作流 1：GHL 到 <span data-t="appName">Your AI Connector</span>

此工作流将来自 GHL 的传入消息转发给 <span data-t="appName">Your AI Connector</span>。

### 第 1 步：创建工作流

1. 在 GHL 中，转到 **Automation > Workflows**。
2. 点击 **Create New Workflow**。
3. 为其命名，例如“Send Message to <span data-t="appName">Your AI Connector</span>”。

### 第 2 步：添加触发器

为您想要转发的每个渠道添加一个触发器：

- Customer Replied - SMS
- Customer Replied - Email
- Customer Replied - Facebook Message
- Customer Replied - Instagram DM
- Customer Replied - Live Chat

您可以添加所有这些渠道，也可以仅添加与您的设置相关的渠道。

### 第 3 步：添加标签过滤器（可选）

如果您只想转发来自特定联系人的消息：

1. 点击触发器上的 **添加筛选器 (Add Filter)**。
2. 将条件设置为“联系人拥有标签 (Contact has tag)”。
3. 选择您的标签。
4. 选择联系人是需要拥有所选标签中的 **任意一个 (any)** 还是 **所有 (all)**。

### 第 4 步：创建渠道拆分

添加一个 **条件 (Condition)** 操作，将每个渠道路由到其对应的 Webhook：

| 分支 | 条件 |
|---|---|
| 分支 1 | 消息来源等于 `Email` |
| 分支 2 | 消息来源等于 `SMS` |
| 分支 3 | 消息来源等于 `Messenger` |
| 分支 4 | 消息来源等于 `Instagram` |
| 分支 5 | 消息来源等于 `Live Chat` |

### 第 5 步：配置 Webhook

为每个分支添加一个 **Webhook / HTTP 请求 (Webhook / HTTP Request)** 操作：

- **方法 (Method)：** `POST`
- **URL：**
  ```
  https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
  ```

- **自定义数据字段 (Custom Data fields)：**

| 字段 | 值 | 备注 |
|---|---|---|
| `messageSid` | `{{right_now.second}}{{contact.id}}` | 唯一消息标识符 |
| `fromId` | `{{contact.id}}` | GHL 联系人 ID |
| `toId` | `{{user.id}}` | 您的 GHL 用户 ID |
| `body` | `{{message.body}}` | 消息内容 |
| `channel` | 见下表 | 必须与分支匹配 |
| `status` | `created` | 始终设置为 `created` |
| `messageType` | `text` | 消息类型 |

**各分支的渠道值：**

| 分支 | `channel` 值 |
|---|---|
| 电子邮件 (Email) | `email` |
| 短信 (SMS) | `sms` |
| Messenger | `messenger` |
| Instagram | `ig` |
| 在线聊天 (Live Chat) | `livechat` |

::: warning
**重要提示：** 请确保 `channel` 值完全匹配——这些值区分大小写。
:::


### 第 6 步：启用重新进入

在工作流设置中，确保启用了 **允许重新进入 (Allow Re-entry)**。否则，将仅转发每个联系人的第一条消息。

---

## 工作流 2：Your AI Connector 到 GHL

此工作流接收来自 Your AI Connector 的回复，并通过正确的 GHL 渠道将其发送给客户。

### 第 1 步：在 GHL 中创建入站 Webhook

1. 在 GHL 中，转到 **Settings > Developers / API**。
2. 点击 **Create New Webhook**（或“Inbound Webhook”）。
3. 将其命名为“Messages”。
4. 保存并**复制 webhook URL** —— 你将在下一步用到它。

### 第 2 步：配置 Your AI Connector

1. 在 Your AI Connector 中，点击侧边栏中的 **Settings**（设置）。
2. 在 **Channels**（渠道）下，点击 **Channels**（渠道）。
3. 滚动到页面最底部的 **Custom channel**（自定义渠道）卡片。
4. 将您刚才复制的 GHL 入站 webhook URL 粘贴到 **Webhook URL** 中（必须是公共 HTTPS 地址），然后点击 **Save**（保存）。

> **这不是 Settings → Integrations → Webhooks 页面。** 该页面用于事件通知，发送的是不同的有效载荷。GHL 出站中继是在 **Settings → Channels** 下的 **Custom channel** 卡片中设置的。

现在，每当有消息发送给联系人时，Your AI Connector 都会自动向 GHL 发送通知。发送的数据如下所示：

```json
{
  "contactId": "NtL97bwnhITrfIq8lWFi",
  "messageId": "s28dtg13qNuhXLoKpcLs",
  "userId": "wpDZRvaw4Hgh4whUBpwlKPRftOi2",
  "body": "Message content here",
  "toId": "qtpBsc6fiqkXTnSOeze3",
  "channel": "email"
}
```

> **导航提示：** 您用于工作流 1 的 API 密钥与您在此处使用的自定义渠道卡片位于不同位置 —— 密钥位于 **Settings → Integrations → API Key**，而此中继的自定义渠道卡片位于 **Settings → Channels** 的底部。独立的 **Settings → Integrations → Webhooks** 页面用于事件通知，发送的是不同的有效载荷；如果您需要的是该功能，请参阅 [Webhooks](webhooks.md)。

### 第 3 步：创建响应工作流

1. 在 GHL 中，转到 **Automation > Workflows**。
2. 创建一个名为“Send Message to Contact”的新工作流。
3. 将触发器设置为 **Inbound Webhook**，并选择你在第 1 步中创建的 webhook。

### 第 4 步：添加查找联系人操作

1. 添加一个 **Find Contact** 操作。
2. 将搜索字段设置为 **Contact ID**。
3. 使用以下值：`{{inboundWebhookRequest.toId}}`

### 第 5 步：添加可选的标签检查

如果您想限制哪些联系人接收来自 Your AI Connector 的消息：

1. 添加一个 **Condition** 操作。
2. 检查联系人是否具有特定标签。
3. 如果缺少该标签，则结束工作流（在 false 分支上添加一个“Stop”操作）。

### 第 6 步：添加渠道拆分

添加一个**条件**操作，根据 `{{inboundWebhookRequest.channel}}` 对消息进行路由：

| 分支 | 条件 | 操作 |
|---|---|---|
| 分支 1 | 等于 `email` | 发送电子邮件 |
| 分支 2 | 等于 `sms` | 发送短信 |
| 分支 3 | 等于 `messenger` | 发送 Facebook 消息 |
| 分支 4 | 等于 `ig` | 发送 Instagram 消息 |
| 分支 5 | 等于 `livechat` | 发送聊天消息 |

### 第 7 步：配置每个发送操作

在每个发送操作中，将消息正文设置为：

```
{{inboundWebhookRequest.body}}
```

### 第 8 步：启用重新进入

与工作流 1 一样，请确保在工作流设置中启用了**允许重新进入**。

---

## 测试集成

### 测试 GHL 到 <span data-t="appName">Your AI Connector</span>（工作流 1）

1. 向您的 GHL 号码或已连接的渠道发送一条消息（例如，给自己发送一条短信）。
2. 打开 <span data-t="appName">Your AI Connector</span> 并确认消息出现在 **Chats** 中。
3. 检查渠道标签是否正确（短信、电子邮件等）。
4. 对您配置的每个渠道重复上述步骤。

### 测试 <span data-t="appName">Your AI Connector</span> 到 GHL（工作流 2）

1. 在 <span data-t="appName">Your AI Connector</span> 中，向联系人发送回复（手动发送或让 AI 回复）。
2. 打开 GHL 并验证联系人是否收到了消息。
3. 确认消息是通过正确的渠道发送的。
4. 检查消息内容是否匹配。

---

## 故障排除

| 问题 | 检查事项 |
|---|---|
| 消息未到达 <span data-t="appName">Your AI Connector</span> | 验证 webhook URL 中的 API 密钥是否正确。检查工作流触发器是否正在触发（GHL 工作流日志）。确认已启用“允许重新进入”（Allow Re-entry）。 |
| 消息未到达 GHL | 验证 GHL 入站 webhook URL 是否正确粘贴到了 **Settings → Channels** 底部 **Custom channel** 卡片的 **Webhook URL** 中（不要粘贴到 Settings → Integrations → Webhooks 页面，那是不同的功能）。检查 GHL 入站 webhook 是否处于活动状态。查看 GHL 工作流执行日志。 |
| 在 GHL 中找不到联系人 | webhook 数据中的 `toId` 必须与现有的 GHL 联系人 ID 匹配。确保两个系统中都存在 ID 匹配的联系人。 |
| 回复时使用了错误的渠道 | 请仔细检查条件分支中的渠道值。它们必须完全匹配：`email`、`sms`、`messenger`、`ig`、`livechat`。 |
| 仅转发了第一条消息 | 在两个工作流设置中都启用 **Allow Re-entry**（允许重新进入）。 |

---

## 后续步骤

- [Webhooks](webhooks.md) — 为其他 <span data-t="appName">Your AI Connector</span> 事件设置 webhooks。
- [API 访问](api-access.md) — 使用 API 进行 GHL 之外的自定义集成。
- [自定义渠道](../messaging-channels/custom-channels.md) — 了解更多关于自定义渠道消息传递的信息。