# Facebook 潜在客户表单
正在投放 Facebook 广告以获取潜在客户？此集成功能可自动将这些潜在客户发送至 Your AI Connector，以便您通过 WhatsApp、短信或任何其他已连接的渠道跟进他们——无需您动手操作。
它的工作原理是通过自动化平台（如 Pabbly、Zapier 或 Make）将 Facebook 潜在客户广告连接到 Your AI Connector。这些平台充当 Facebook 和 Your AI Connector 之间的桥梁，使用 API（一种让不同软件自动交换数据的方式）将潜在客户信息从一方传递到另一方。
---
## 前置条件
在开始之前，请确保您已准备好：
- 拥有创建潜在客户广告权限的 **Facebook 广告管理工具**访问权限。
- **一个账户**，且具有有效的 API 密钥（在 **设置 → 集成 → API 密钥** 中生成 — 请参阅 [API 访问](api-access.md) 获取具体步骤）。
- **一个自动化平台**账户 — Pabbly Connect、Zapier 或 Make (Integromat)。本指南以 Pabbly 为例，但在任何平台上步骤都是相似的。
- **一个 Your AI Connector 中的联系人列表**，用于添加新的潜在客户 — 请参阅 [组织列表和联系人](../get-started/list-and-contact-management.md)。
---
## 概览
该集成分为三个阶段：
1. 潜在客户填写您的 Facebook 潜在客户表单。
2. 您的自动化平台检测到新潜在客户，并自动将信息发送至 Your AI Connector（使用两个 API 调用）。
3. Your AI Connector 创建联系人并将其添加到您指定的列表中。
此后，您分配的广播、营销活动或 AI 代理将处理后续事宜 — 无论是 AI 驱动的欢迎消息、滴灌序列，还是人工跟进。
---
## 第 1 步：创建您的 Facebook 潜在客户表单
1. 打开 **Facebook 广告管理工具**。
2. 创建一个以 **潜在客户** 为目标的新广告系列。
3. 在广告层级，选择 **即时表单** 作为潜在客户获取方式。
4. 使用您需要的字段构建表单。至少应包含：
- **名字**
- **电话号码**（带国家/地区代码）
- 可选：姓氏、电子邮件
5. 发布广告或将表单保存为草稿以供测试。
---
## 第 2 步：测试潜在客户表单
在连接自动化流程之前，请提交一个测试潜在客户：
1. 在广告管理工具中，转到您的潜在客户表单。
2. 点击 **预览** 并使用测试数据填写表单。
3. 确认测试潜在客户出现在您的 **Facebook 潜在客户中心**（位于 Facebook 主页的“发布工具”下，或广告管理工具的“潜在客户”下）。
此测试条目将用于在您的自动化平台中设置字段映射。
---
## 第 3 步：设置自动化流程
### 将 Facebook Lead Ads 设置为触发器
1. 登录您的自动化平台（Pabbly、Zapier 或 Make）。
2. 创建一个新的工作流 / 场景 / Zap。
3. 将**触发器**设置为 "Facebook Lead Ads - New Lead"。
4. 连接您的 Facebook 账户并选择页面和潜在客户表单。
5. 获取测试潜在客户以确认连接正常并映射字段。
### 配置 API 调用 1：创建联系人
添加一个包含 HTTP / Webhook / API 请求的操作步骤：
- **方法：** `POST`
- **URL：** `https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY`
- **请求头：**
```
Content-Type: application/json
```
- **正文 (JSON)：**
```json
{
"firstName": "{{first_name}}",
"lastName": "{{last_name}}",
"phone": "{{phone_number}}",
"email": "{{email}}"
}
```
将 `{{placeholders}}` 替换为您触发步骤中的实际字段映射。
::: warning
**重要提示：** 电话号码必须包含国家/地区代码（例如，美国为 `+1`，荷兰为 `+31`）。如果您的潜在客户表单收集的电话号码不含国家/地区代码，请在自动化流程中添加一个格式化步骤来添加前缀。
:::
API 响应会在 `data.contactId` 返回新联系人的 ID。请保存该值——下一步需要用到它。
> **您可以跳过第二次调用。** `POST /v1/contacts` 在创建主体中也接受 `listId`（一个列表）或 `listIds`（多个列表），这会在同一个请求中将新联系人添加到这些列表中。仅当您的自动化平台需要在决定使用哪个列表之前确认联系人已存在时，才使用下方的两步版本。
### 配置 API 调用 2：将联系人添加到列表
添加第二个操作步骤：
- **方法：** `POST`
- **URL：** `https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY`
- **标头：**
```
Content-Type: application/json
```
- **正文 (JSON)：**
```json
{
"contactId": "{{contact_id_from_previous_step}}",
"listId": "YOUR_LIST_ID"
}
```
将 `YOUR_LIST_ID` 替换为您联系人列表的实际 ID（请参阅下方的 [查找您的列表 ID](#finding-your-list-id)），并将 `contactId` 映射到第一次 API 调用返回的 `data.contactId`。
---
## 查找您的列表 ID
1. 在 Your AI Connector 中，点击 **联系人**，然后点击 **列表** 选项卡。
2. 打开您所需列表旁边的行菜单（“⋯”），然后点击 **复制列表 ID**。
请参阅 [组织列表与联系人](../get-started/list-and-contact-management.md) 以获取“列表”页面的完整操作指南。
---
## 第 4 步：测试完整工作流程
1. 通过您的 Facebook 表单提交另一个测试潜在客户（或在您的自动化平台中重放现有的测试潜在客户）。
2. 检查 Your AI Connector 以确认：
- **联系人**已创建，且姓名、电话号码和电子邮件正确无误。
- 联系人已**添加到正确的列表**中。
3. 如果您设置了广播、营销活动或 AI 代理来自动向该列表发送消息，请确认其是否按预期触发。
---
## 数据参考
以下是集成过程中发送和接收的数据示例。
### 创建联系人 - 请求
```json
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
{
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15551234567",
"email": "jane@example.com"
}
```
### 创建联系人 - 响应
```json
{
"success": true,
"data": {
"message": "Successfully created new contact",
"contactId": "abc123xyz",
"listsAdded": []
}
}
```
### 将联系人添加到列表 - 请求
```json
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
{
"contactId": "abc123xyz",
"listId": "LIST_ID"
}
```
---
## 提示
- **重复处理：** 如果具有相同电话号码的联系人已存在，创建调用将返回 `{"success": false, "error_code": 409}`，且不会返回现有的联系人。请根据 `error_code`（HTTP 状态码为 200）进行分支处理，并在添加到列表的调用之前使用 `GET /v1/contacts?phoneNumber=...` 查找该联系人。
- **多个表单：** 为不同的潜在客户表单创建单独的自动化工作流，每个工作流针对不同的列表以及不同的广播、营销活动或 AI 代理。
- **错误通知：** 配置您的自动化平台，以便在 API 调用失败时通知您，从而避免丢失潜在客户。
---
## 后续步骤
- [从营销活动迁移到广播与代理](../moving-from-campaigns.md) — 设置自动向新潜在客户发送消息的功能。
- [API 访问](api-access.md) — 用于高级集成的完整 API 文档。
- [Webhooks](webhooks.md) — 在联系人被创建或添加标签时获取通知。