Your AI Connector Docs

API 入门

Your AI Connector REST API 让您能够在您的账户之上构建自己的集成。您可以创建和查询联系人、管理营销活动、常见问题解答、任务和预约、发送消息、注册 Webhook、读取分析数据以及连接消息渠道——仪表板能做的所有事情，都可以通过代码驱动。

这是 API 文档的中心页面。如果您要将 Your AI Connector 连接到已经内置集成的工具，您可能根本不需要使用 API。API 专为自定义集成和大规模自动化而设计。

注意： 这些页面是为开发人员编写的。如果您不是开发人员，请将此部分分享给您的技术团队。

基础 URL

每个请求都发送到同一个基础 Web 地址，本文档中的所有路径均相对于该地址：

https://api.youraiconnector.com/v1

因此，营销活动端点是 https://api.youraiconnector.com/v1/campaigns，联系人端点是 https://api.youraiconnector.com/v1/contacts，依此类推。

所有请求都必须使用安全连接 (HTTPS)。普通的 HTTP 请求将被拒绝。

获取 API 密钥

API 访问是一项付费功能。如果您的套餐不包含此功能，每个请求都将返回 403，并包含以下正文：

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

一旦您的套餐启用了 API 访问权限，即可从仪表板生成密钥。完整的操作步骤请参阅 API 访问 — 简而言之：前往 设置 → 集成 → API 密钥 以生成或重新生成您的密钥。API 密钥是“集成”下的一个独立部分，与 Webhooks 分开，且仅在您的套餐启用 API 访问权限后才会显示。请像对待密码一样保管该密钥：它拥有对您账户的完全访问权限。

身份验证

您可以通过四种方式发送 API 密钥。所有方式在每个接受 API 密钥验证的端点上均有效。

方法 如何操作 适用场景
查询参数 ?apiKey=YOUR_API_KEY 快速测试、浏览器 URL、旧版设置
标头 X-API-Key: YOUR_API_KEY 生产环境集成
Bearer 标头 Authorization: Bearer YOUR_API_KEY 生产环境集成
Firebase ID 令牌 Authorization: Bearer <ID token> 仅限第一方应用会话

对于生产环境，建议优先使用标头形式，这样您的密钥就不会出现在服务器日志或浏览器历史记录中。查询参数形式始终有效，且对于一次性测试最为简单。

请参阅 身份验证 以获取每种方法的详细说明，包括示例以及何时使用哪种方法的指导。

您的第一个请求

这是一个完整且可运行的调用示例，用于列出您账户下的营销活动。它使用您的 API 密钥，并按时间倒序返回最近的营销活动。

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

成功的响应如下所示：

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

成功与错误响应

每个 JSON 响应都包含一个 success 标志，因此您无需解析状态码即可进行分支判断。

成功的响应包含 success: true 以及该端点的数据（字段名称各不相同，例如 campaigns、contacts、data 等）：

{
  "success": true,
  "campaigns": []
}

失败的响应包含 success: false、一条人类可读的 error 消息以及一个与 HTTP 状态码相匹配的数字 error_code：

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

在读取数据之前，请务必检查 success（或 HTTP 状态码）。有关完整状态码表以及如何对大型结果集进行分页的信息，请参阅 错误与分页。

速率限制

已认证的请求限制为每个 API 密钥 每分钟 300 次请求。此外，每个账户还有一个更宽泛的上限，即 每分钟 1,200 次请求，该上限计算针对该账户进行的所有已认证请求。

如果您超过了任一限制，将会收到 429 响应：

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

请稍作等待后重试。您还可以随时使用 GET https://api.youraiconnector.com/v1/api-keys/usage 检查当前的使用情况，它会返回您在当前窗口中已使用的请求次数以及重置时间，这对于构建客户端限流功能非常有用。请参阅 API 密钥。

资源指南

下方的每个资源组都有其专属指南，其中包含确切的路径、请求字段和响应格式。

资源 涵盖内容
AI 智能体 创建和配置 AI 智能体：设置、活跃时间、知识库、标记规则、工具、媒体和草稿
入口点 决定哪个 AI 智能体回答新对话：渠道默认设置、每个 WhatsApp 号码对应一个智能体、关键词、评论和关注者规则
广播 创建、定价、启动、暂停和复制发送给联系人列表的一次性消息
营销活动 创建、更新、复制、启用、归档和检查营销活动及其机器人配置
联系人 创建、查找、列出、更新、导入、标记和删除联系人
常见问题解答 管理 AI 助手使用的问答条目，并将它们链接到营销活动
知识库 将网站和文档导入 AI 的知识库，并将常见问题解答分组
任务 创建和管理 CRM 任务、看板阶段和任务类型
消息 发送出站消息并读取对话历史记录
预约 预订、重新安排、取消和删除预约
渠道 连接和断开消息渠道、购买号码，并设置每个渠道上由哪个 AI 智能体回答新对话
模板 创建、提交 WhatsApp 消息模板并检查其审批状态
分析 读取每日消息事件统计数据、额度使用情况和 AI 成本汇总
Webhook 注册端点以接收实时事件通知
团队 管理团队成员、邀请、角色、权限和部门
API 密钥 检查、轮换和撤销您的 API 密钥，查看速率限制使用情况，并创建具有受限访问权限的额外密钥

代理、入口点和广播

AI 智能体、入口点和广播均包含在已发布的 OpenAPI 规范中，因此您可以在 API 浏览器 中浏览它们的精确字段并运行实时请求。每个资源都有对应的指南：AI 智能体、入口点 和 广播。

以 Markdown 格式阅读这些文档

本说明文档中的每一页都有一个纯 Markdown 版本：只需在页面地址末尾添加 /index.md 即可。因此，当前页面也可通过 https://docs.youraiconnector.com/api/getting-started/index.md 访问，它将以纯文本而非网页形式返回——当您需要将页面内容粘贴到 AI 助手或通过脚本获取时，这非常方便。

若要遍历整个文档集，请从 https://docs.youraiconnector.com/sitemap.xml 开始，其中列出了我们发布的所有页面。请注意，本说明文档特意未被搜索引擎收录，因此直接获取这些地址是从代码中访问文档的途径。

目前尚无受密钥保护的文档端点，也暂不支持批量下载——Markdown 版本和站点地图构成了全部接口，且两者均无需 API 密钥。

后续步骤

  • 身份验证 — 为您的集成选择合适的身份验证方法。
  • 错误与分页 — 处理失败情况并对结果进行分页。
  • API 访问 — 生成您的密钥并查看示例。