端到端构建集成

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

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

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

开始之前。 API 访问是一项付费功能。如果您的套餐不包含此功能，每个请求都将返回 403。请参阅 API 访问以确认其已启用，并参阅身份验证以了解传递密钥的所有方式。

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

https://api.youraiconnector.com/v1

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

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

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

cURL

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

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

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 进行分页的信息，请参阅错误与分页。

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

第 2 步 — 创建 AI 智能体

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

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

cURL

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

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

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

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

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

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

配置助手

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

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 指南。

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

第 3 步 — 连接渠道

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

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

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

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

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

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

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" }'

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

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

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

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

{
  "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 视为终止性故障。

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)

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 步中创建的智能体：

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 流程的信息，请参阅渠道指南。

第 4 步 — 导入您的联系人

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

cURL

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

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

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")

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

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

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

第 5 步 — 发送和读取消息

发送消息

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

cURL

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

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

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。）

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

读取对话

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

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

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) 进行过滤。消息指南涵盖了媒体附件、标记消息为已读以及按会话查看消息的内容。

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

第 6 步 — 读取分析数据

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

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

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();

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 成本明细，请参阅分析指南。

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

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

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

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

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

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

cURL

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

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

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"]

{
  "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 指南以及集成级别的 Webhook 页面。

总结

以下是整个流程的概览：

步骤	目标	关键调用
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 即可。在此基础上，您可以根据需要逐步深入了解各资源的指南：

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

端到端构建集成 #

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

第 2 步 — 创建 AI 智能体 #

配置助手 #

第 3 步 — 连接渠道 #

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

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

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

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

发送消息 #

读取对话 #

第 6 步 — 读取分析数据 #

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

总结 #

端到端构建集成

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

第 2 步 — 创建 AI 智能体

配置助手

第 3 步 — 连接渠道

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

将渠道路由到您的智能体

第 4 步 — 导入您的联系人

第 5 步 — 发送和读取消息

发送消息

读取对话

第 6 步 — 读取分析数据

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

总结