# 端到端构建集成

本指南将引导您完成从自己的代码运行 <span data-t="appName">Your AI Connector</span> 所需的一切，而无需打开仪表板。到最后，您将构建一个最小集成，实现以下功能：

1. 使用 API 密钥进行身份验证
2. 创建 AI 智能体并配置其助手行为
3. 连接消息渠道（我们以 WhatsApp Web 为例）并将其指向该智能体
4. 导入联系人
5. 发送和读取消息
6. 读取分析数据
7. 订阅 Webhook 以获取实时事件

每一步都链接到完整的资源指南，以便您在需要时深入了解详细信息。此页面是地图；资源指南则是实地指南。

> **开始之前。** API 访问是一项付费功能。如果您的套餐不包含此功能，每个请求都将返回 `403`。请参阅 [API 访问](../integrations/api-access.md) 以确认其已启用，并参阅 [身份验证](authentication.md) 以了解传递密钥的所有方式。

以下所有路径均相对于基础 URL：

```
https://api.youraiconnector.com/v1
```

---

## 第 1 步 — 获取 API 密钥并发出您的第一个请求

您的 API 密钥位于应用内的 **设置 → 集成 → API 密钥** 中 — 这是“集成”下的一个独立部分，与 Webhook 分开，仅在套餐包含 API 访问权限时才会显示。生成密钥后，请将其复制并妥善保存（存放在服务器端的密钥存储库或环境变量中 — 切勿放在浏览器代码中）。完整说明请参阅 [API 访问](../integrations/api-access.md)。

获得密钥后，通过调用健康检查端点来确认其是否有效。发送密钥的方法有多种；最简单的是使用 `?apiKey=` 查询参数，但在实际代码中，建议使用 `X-API-Key` 请求头，这样密钥就不会出现在服务器日志或浏览器历史记录中。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }
```

**Python**

```python
import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }
```

每个成功的响应都封装在相同的信封中 — 一个 `success: true` 字段加上结果数据。错误会返回 `success: false`，其中包含 `error` 消息和 `error_code`。有关完整列表以及列表端点如何使用 `?limit` 和 `?cursor` 进行分页的信息，请参阅 [错误与分页](errors-and-pagination.md)。

> **速率限制。** 经过身份验证的请求上限为 **每分钟 300 次**（每个账户的上限为每分钟 1,200 次）。超过限制将返回 `429`；请退避并重试。

---

## 第 2 步 — 创建 AI 智能体

**AI 智能体**是承载助手行为的单元：包括其指令、目标、活跃时间以及与联系人的沟通方式。它是处理对话的核心，因此这是首先需要创建的内容。

使用 `POST /agents` 创建一个智能体。`name` 是唯一需要预先发送的字段；其他所有内容都可以通过下方的 bot-config 调用进行设置。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]
```

创建成功后将返回 `201` 以及新的 ID：

```json
{
  "success": true,
  "agent_id": "abc123agent"
}
```

**保存 `agent_id`** — 您在路由渠道时将会用到它。

### 配置助手

`PUT /agents/{agentId}/bot-config` 用于设置助手的行为。它会将您发送的字段*合并*到现有配置中，因此您未发送的任何字段都将被保留：

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'
```

使用 `PUT /agents/{agentId}/active-hours` 设置活跃时间，以便助手仅在工作时间内回复；在这些时间窗口之外，它不会自动回复。

> **知识库。** 若要让助手根据您自己的内容进行回答，请附加常见问题解答（FAQs）。请参阅 [FAQs 指南](faqs.md)。

> **旧版：经典营销活动。** 仍拥有 **营销活动 (Campaigns)** 页面的账户会在营销活动上创建相同的助手行为（使用 `POST /campaigns` 配合 `type` 和 `bot` 对象，然后使用 `PUT /campaigns/{campaignId}/bot-config`）。完整的营销活动字段列表和生命周期控制请参阅 [营销活动指南](campaigns.md)。如果您正在构建新内容，请创建智能体。

---

## 第 3 步 — 连接渠道

智能体需要一种发送和接收消息的方式。可以通过 API 驱动七种连接流程：WhatsApp Business、WhatsApp Web、Instagram 和 Messenger（共享同一个 Meta 流程）、Instagram 个人账户、Telegram、LINE 和 Viber。其余渠道（包括短信、电子邮件、聊天小部件和自定义渠道）是在仪表板中而非通过 REST 进行设置的，一旦连接，消息、联系人和路由端点对它们的作用方式完全相同。`GET /channels` 是当前账户实际连接内容的实时真实来源：

```bash
curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"
```

每个渠道的完整连接/断开连接流程记录在 [渠道指南](channels.md) 中。下面我们将完整演示 **WhatsApp Web** 的操作，因为它展示了最典型的模式：一种需要您的封装程序进行渲染和轮询的二维码配对流程。

### 示例：通过二维码配对 WhatsApp Web

WhatsApp Web 配对是一个包含三个步骤的交互过程 — **开始**、**获取二维码**、**轮询直至连接**。

**1. 开始配对会话。** 以 E.164 格式传入您想要连接的号码。

```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'
```

```javascript
await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
```

```python
requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)
```

**2. 获取二维码并展示给用户。** 每 10–15 秒轮询一次。响应包含原始 `qr_code` 有效载荷（请自行将其渲染为二维码图像）以及一个可直接显示的 `qr_data_url`。

```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"
```

```json
{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}
```

在您的封装程序 UI 中，将 `qr_data_url` 直接放入 `<img src="...">`，并要求用户通过手机上的 **WhatsApp → 已关联设备** 进行扫描。如果二维码过期（返回 `410` 响应），请从第 1 步重新开始以获取新的二维码。

**3. 轮询状态直至连接成功。** 用户扫描后，请持续轮询状态端点，直到它报告 `connected`（服务也可能报告 `open`）。请将 `disconnected` 和 `not_initialized` 视为终止性故障。

```python
import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)
```

```javascript
async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}
```

> **注意。** 每个已连接的 WhatsApp Web 号码都会产生循环的月度维护费用，直到您将其断开连接 (`DELETE /channels/whatsapp-web/connections/{phoneNumber}`)。

### 将渠道路由到您的智能体

连接渠道使其能够工作；路由则告诉平台*哪个 AI 智能体*应该回复该渠道上的全新入站对话。为该渠道设置默认入口点（Entry Point），并指定您在第 2 步中创建的智能体：

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'
```

每个渠道重复此调用一次 — 每个渠道对应一个渠道默认值。若要让某个渠道不分配智能体回复，请调用 `DELETE /entry-points/channel-defaults?channel=whatsapp_web`；若要检查账户的入口点层级是否处于活动状态，请调用 `GET /entry-points/routing-status`。旧的 `POST /channels/campaign` 映射仅保留用于回滚，不再用于入站路由。有关其他渠道类型和 WhatsApp Business OAuth 流程的信息，请参阅 [渠道指南](channels.md)。

---

## 第 4 步 — 导入您的联系人

渠道上线后，加载您想要触达的人员。导入端点**每次调用最多可处理 500 条记录**。每条记录都需要一个国际格式的 `phone_number`；其他所有信息均为可选。号码错误、不支持的渠道或已存在的号码的记录将被跳过——系统会报告每条被跳过记录的索引和原因，以便您仅重试失败的记录。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);
```

**Python**

```python
res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")
```

响应会准确告知您发生了什么：

```json
{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}
```

有关逐个创建、列表/查询、列表、标签和自定义字段的信息，请参阅[联系人指南](contacts.md)。

---

## 第 5 步 — 发送和读取消息

### 发送消息

最简单的发送方式是**与渠道无关的**：提供联系人的身份信息和消息正文，平台会自动通过联系人所在的任何渠道进行投递。您可以按 `contact_id` 定位，也可以按 `channel` 加上匹配的身份字段（WhatsApp/WhatsApp Web/SMS 使用 `phone_number`，Instagram 使用 `instagram_id`，依此类推）进行定位。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]
```

投递是**异步的**——收到 `201` 表示消息已*被接受并进入队列*，尚未投递。（开启免打扰或隐私模式的联系人会被拒绝，并返回 `422`。）

```json
{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}
```

### 读取对话

要读取回复的消息，请按联系人列出消息，按最新时间排序，并使用游标分页。将一个响应中的 `next_cursor` 作为下一个响应的 `cursor` 传入，以回溯历史记录。

```bash
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"
```

```python
res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page
```

您还可以按内容类型 (`?filter=text|media|tool_use`) 或方向 (`?direction=inbound|outbound`) 进行过滤。[消息指南](messages.md)涵盖了媒体附件、标记消息为已读以及按会话查看消息的内容。

> **不要轮询回复。** 定时列出消息虽然可行，但会浪费请求并增加延迟。对于传入的消息，请改用 Webhook——这是第 7 步的内容。

---

## 第 6 步 — 读取分析数据

一旦消息开始流动，分析摘要将为您提供日期范围内的汇总计数：已发送、已送达、已阅读、已回复、已预订、已创建联系人以及已消耗/充值的额度。您将获得范围总计和每日零填充序列，非常适合仪表板图表。您可以选择使用 `campaign_id` 将其限定为单个营销活动（以下示例使用占位符营销活动 ID `abc123campaign`）；如果不带该参数，则显示整个账户的总计。

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"
```

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();
```

```python
res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]
```

日期范围默认为过去 30 天，上限为 366 天。有关逐项额度使用记录和 AI 成本明细，请参阅[分析指南](analytics.md)。

---

## 第 7 步 — 订阅 Webhook 以获取实时事件

轮询对于快速脚本来说尚可，但真正的集成应该基于**推送**。Webhook 允许平台在发生特定事件（如新联系人、回复、预约成功、聊天结束）时立即调用*您的*服务器。

首先，查看您可以订阅的确切事件名称：

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"
```

```json
{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}
```

然后，创建一个指向您服务器上 HTTPS URL 的订阅。请使用上述调用中提供的确切事件字符串。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'
```

**JavaScript**

```javascript
const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();
```

**Python**

```python
res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]
```

```json
{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

该 URL 必须使用 HTTPS 且可公开访问。此后，您的服务器将为每个已订阅的事件接收一个 POST 请求。您可以发送测试交付、检查订阅的健康状况，并重新启用因多次失败而被自动禁用的订阅——有关有效载荷格式和验证，请参阅[ Webhook 指南](webhooks.md)以及集成级别的[ Webhook](../integrations/webhooks.md) 页面。

---

## 总结

以下是整个流程的概览：

| 步骤 | 目标 | 关键调用 |
|---|---|---|
| 1 | 身份验证 | `GET /health` |
| 2 | 创建并调整助手 | `POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours` |
| 3 | 连接渠道并进行路由 | `POST /channels/whatsapp-web/connections` → 轮询二维码 + 状态 → `PUT /entry-points/channel-defaults` |
| 4 | 加载联系人 | `POST /contacts/import` |
| 5 | 发送与读取 | `POST /contacts/send`, `GET /contacts/{id}/messages` |
| 6 | 衡量 | `GET /analytics/summary` |
| 7 | 实时响应 | `POST /webhooks` |

一个最小化的包装器只需将这七个调用接入您自己的 UI 即可。在此基础上，您可以根据需要逐步深入了解各资源的指南：

- [营销活动](campaigns.md) · [联系人](contacts.md) · [常见问题解答](faqs.md) · [消息](messages.md) · [预约](appointments.md)
- [渠道](channels.md) · [模板](templates.md) · [分析](analytics.md) · [Webhook](webhooks.md) · [API 密钥](api-keys.md)
- 新手入门？[快速开始](getting-started.md) · [身份验证](authentication.md) · [错误与分页](errors-and-pagination.md)

Stuck on something this guide does not cover? Email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com).