# API 入门

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

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

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


---

## 基础 URL

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

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

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

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

---

## 获取 API 密钥

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

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

一旦您的套餐启用了 API 访问权限，即可从仪表板生成密钥。完整的操作步骤请参阅 [API 访问](../integrations/api-access.md) — 简而言之：前往 **设置 → 集成 → 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>` | 仅限第一方应用会话 |

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

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

---

## 您的第一个请求

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

**cURL**

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

**JavaScript**

```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**

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

成功的响应如下所示：

```json
{
  "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` 等）：

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

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

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

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

---

## 速率限制

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


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

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

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

---

## 资源指南

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

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

### 代理、入口点和广播

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


---

## 以 Markdown 格式阅读这些文档

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

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

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

---

## 后续步骤

- [身份验证](authentication.md) — 为您的集成选择合适的身份验证方法。
- [错误与分页](errors-and-pagination.md) — 处理失败情况并对结果进行分页。
- [API 访问](../integrations/api-access.md) — 生成您的密钥并查看示例。