# API 入门

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

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

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


---

## 基础 URL

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

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

因此，AI 智能体端点是 `https://api.dmchamp.com/v1/agents`，联系人端点是 `https://api.dmchamp.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) 以获取每种方法的详细说明，包括示例以及何时使用哪种方法的指导。

---

## 您的第一个请求

这是一个完整且可运行的调用示例，用于列出您账户下的 AI 智能体。它使用您的 API 密钥，并为每个智能体返回一行简短信息，按最新日期排序。

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

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

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    params={"view": "summary"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["agents"])
```

成功的响应如下所示：

```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 次请求**，该上限计算针对该账户进行的所有已认证请求。

::: master-only
代理商请注意：第二个数字是您需要规划的重点。即使您使用代理商密钥针对子账户进行操作（通过 `sub_account_id`），这些请求仍会计入您的代理商账户额度，因此跨多个客户的配置突发流量会共享同一个预算。如果某个客户需要独立的预算，请使用该子账户自己的 API 密钥。
:::

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

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

请稍作等待后重试。您还可以随时使用 `GET https://api.dmchamp.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)。

::: master-only
包含在规范中也意味着这些端点会作为工具显示在任何您 [通过 MCP 连接](../integrations/connect-ai-clients.md) 的 AI 助手中。
:::

---

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

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

对于 AI 助手或需要读取整个集合的脚本，有两个现成的文件：

- `https://docs.dmchamp.com/llms.txt` — 索引：每个页面都包含一行摘要和指向其 Markdown 副本的链接，并按照侧边栏的方式进行分组。
- `https://docs.dmchamp.com/llms-full.txt` — 整个文档的单个 Markdown 文件。每个页面都以标题开头，并包含一行 `Source:` 来保存页面地址，以便助手可以引用答案的来源。

这两种文件也存在于每种语言中，位于语言前缀下（`https://docs.dmchamp.com/nl/llms.txt`、`https://docs.dmchamp.com/es/llms-full.txt` 等）。将 `llms.txt` 地址提供给您的助手，它就会获取所需的页面；或者当它需要一次性获取所有上下文时，将其指向 `llms-full.txt`。它们会随文档的每次更改而重建，因此永远不会过时。

如果您想亲自浏览页面，`https://docs.dmchamp.com/sitemap.xml` 列出了我们发布的所有页面。文档特意避开了搜索引擎，因此直接获取这些地址是从代码访问文档的方式。

这一切都不需要 API 密钥：Markdown 副本、两个 `llms` 文件和站点地图就是全部接口。

---

## 后续步骤

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