API 入门
DM Champ REST API 让您能够在您的账户之上构建自己的集成。您可以创建和查询联系人、管理营销活动、常见问题解答、任务和预约、发送消息、注册 Webhook、读取分析数据以及连接消息渠道——仪表板能做的所有事情，都可以通过代码驱动。
这是 API 文档的中心页面。如果您要将 DM Champ 连接到已经内置集成的工具，您可能根本不需要使用 API。API 专为自定义集成和大规模自动化而设计。
注意： 这些页面是为开发人员编写的。如果您不是开发人员，请将此部分分享给您的技术团队。
基础 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，并包含以下正文：
{
"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> |
仅限第一方应用会话 |
对于生产环境，建议优先使用标头形式，这样您的密钥就不会出现在服务器日志或浏览器历史记录中。查询参数形式始终有效，且对于一次性测试最为简单。
请参阅 身份验证 以获取每种方法的详细说明，包括示例以及何时使用哪种方法的指导。
您的第一个请求
这是一个完整且可运行的调用示例，用于列出您账户下的 AI 智能体。它使用您的 API 密钥，并为每个智能体返回一行简短信息，按最新日期排序。
cURL
curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary"
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
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"])
成功的响应如下所示：
{
"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 次请求，该上限计算针对该账户进行的所有已认证请求。
代理商请注意：第二个数字是您需要规划的重点。即使您使用代理商密钥针对子账户进行操作（通过 sub_account_id），这些请求仍会计入您的代理商账户额度，因此跨多个客户的配置突发流量会共享同一个预算。如果某个客户需要独立的预算，请使用该子账户自己的 API 密钥。
如果您超过了任一限制，将会收到 429 响应：
{
"success": false,
"error_code": 429,
"error": "Rate limit exceeded. Please try again later."
}
请稍作等待后重试。您还可以随时使用 GET https://api.dmchamp.com/v1/api-keys/usage 检查当前的使用情况，它会返回您在当前窗口中已使用的请求次数以及重置时间，这对于构建客户端限流功能非常有用。请参阅 API 密钥。
资源指南
下方的每个资源组都有其专属指南，其中包含确切的路径、请求字段和响应格式。
| 资源 | 涵盖内容 |
|---|---|
| AI 智能体 | 创建和配置 AI 智能体：设置、活跃时间、知识库、标记规则、工具、媒体和草稿 |
| 入口点 | 决定哪个 AI 智能体回答新对话：渠道默认设置、每个 WhatsApp 号码对应一个智能体、关键词、评论和关注者规则 |
| 广播 | 创建、定价、启动、暂停和复制发送给联系人列表的一次性消息 |
| 营销活动 | 创建、更新、复制、启用、归档和检查营销活动及其机器人配置 |
| 联系人 | 创建、查找、列出、更新、导入、标记和删除联系人 |
| 常见问题解答 | 管理 AI 助手使用的问答条目，并将它们链接到营销活动 |
| 知识库 | 将网站和文档导入 AI 的知识库，并将常见问题解答分组 |
| 任务 | 创建和管理 CRM 任务、看板阶段和任务类型 |
| 消息 | 发送出站消息并读取对话历史记录 |
| 预约 | 预订、重新安排、取消和删除预约 |
| 渠道 | 连接和断开消息渠道、购买号码，并设置每个渠道上由哪个 AI 智能体回答新对话 |
| 模板 | 创建、提交 WhatsApp 消息模板并检查其审批状态 |
| 分析 | 读取每日消息事件统计数据、额度使用情况和 AI 成本汇总 |
| Webhook | 注册端点以接收实时事件通知 |
| 团队 | 管理团队成员、邀请、角色、权限和部门 |
| API 密钥 | 检查、轮换和撤销您的 API 密钥，查看速率限制使用情况，并创建具有受限访问权限的额外密钥 |
代理、入口点和广播
AI 智能体、入口点和广播均包含在已发布的 OpenAPI 规范中，因此您可以在 API 浏览器 中浏览它们的精确字段并运行实时请求。每个资源都有对应的指南：AI 智能体、入口点 和 广播。
包含在规范中也意味着这些端点会作为工具显示在任何您 通过 MCP 连接 的 AI 助手中。
以 Markdown 格式阅读这些文档
本说明文档中的每一页都有一个纯 Markdown 版本：只需在页面地址末尾添加 /index.md 即可。因此，当前页面也可通过 https://docs.youraiconnector.com/api/getting-started/index.md 访问，它将以纯文本而非网页形式返回——当您需要将页面内容粘贴到 AI 助手或通过脚本获取时，这非常方便。
对于 AI 助手或需要读取整个集合的脚本，有两个现成的文件：
https://docs.youraiconnector.com/llms.txt— 索引：每个页面都包含一行摘要和指向其 Markdown 副本的链接，并按照侧边栏的方式进行分组。https://docs.youraiconnector.com/llms-full.txt— 整个文档的单个 Markdown 文件。每个页面都以标题开头，并包含一行Source:来保存页面地址，以便助手可以引用答案的来源。
这两种文件也存在于每种语言中，位于语言前缀下（https://docs.youraiconnector.com/nl/llms.txt、https://docs.youraiconnector.com/es/llms-full.txt 等）。将 llms.txt 地址提供给您的助手，它就会获取所需的页面；或者当它需要一次性获取所有上下文时，将其指向 llms-full.txt。它们会随文档的每次更改而重建，因此永远不会过时。
如果您想亲自浏览页面，https://docs.youraiconnector.com/sitemap.xml 列出了我们发布的所有页面。文档特意避开了搜索引擎，因此直接获取这些地址是从代码访问文档的方式。
这一切都不需要 API 密钥：Markdown 副本、两个 llms 文件和站点地图就是全部接口。