API 访问
API(应用程序编程接口)是不同软件系统之间进行通信的一种方式。DM Champ API 允许您(或您的开发人员)自动创建联系人、发送消息、管理列表以及从自定义渠道接收传入消息——所有这些都无需使用仪表板。
Prefer to see it? Click through the whole flow:
为什么要使用 API? 如果您想将应用程序连接到没有内置集成的工具,或者需要大规模自动化重复性任务,API 就是实现这一目标的方法。
注意: 本页面性质偏向技术。如果您是企业主而非开发人员,建议您将此页面分享给您的技术团队或自由职业开发人员。
生成您的 API 密钥
注意: API 访问是符合条件的套餐中提供的一项付费功能。如果您的套餐不包含此功能,API 请求将被拒绝并返回 403 响应。如果不确定是否启用了 API 访问,请检查您的套餐或联系支持团队。
- 在左侧边栏中,点击 Settings(齿轮图标)。
- 在 Settings 侧边栏的 Integrations 组下,点击 API Key。

API Key 位于“设置”中的“集成”组下,与 Webhooks 和 Booking & Calendar 并列。
- 如果您还没有密钥,请点击 Generate API key。
- 如果您已经拥有一个密钥,它将以掩码形式显示在 Your key 下方。如果您的密钥支持,请点击 Show 以显示它,然后点击 Copy 进行复制——您将看到一条确认提示。
- 请将密钥存放在安全的地方——每次 API 请求都需要用到它。

您的密钥显示为已遮盖状态。旧密钥可能会显示“无法显示您的密钥”,而不是“显示/复制”——密钥仍然有效,只是您无法在不重新生成的情况下再次查看明文。重新生成卡片位于同一部分的下方,而不是单独的页面。
注意: 部分账户会看到“Your key can’t be displayed”而不是 Show/Copy 控件——这是因为密钥是在应用程序支持重新显示功能之前创建的。该密钥仍然可以正常工作;只有在确实需要再次查看明文时,才需要使用 Regenerate(在密钥卡片下方,同一部分中)。重新生成会立即作废旧密钥,并导致所有使用该密钥的集成失效,直到您粘贴新密钥为止——请在重新生成后立即更新您的集成。
重要提示: 您的 API 密钥就像密码一样——它授予对您账户的完全访问权限。请勿公开分享或将其发布在他人可见的地方。如果您认为密钥已泄露,请立即重新生成。
团队成员: API 密钥属于账户所有者,因此如果您是以受邀团队成员(包括管理员)身份登录,该部分将显示一条说明,而不是密钥。请以账户所有者身份登录以查看、复制或重新生成密钥——这也适用于作用域密钥。
在客户账户内工作的代理机构: 当您从代理机构账户打开客户的仪表板时,您可以像客户本人一样查看、复制和重新生成该客户的密钥,并为其创建作用域密钥。如果团队成员对客户的访问权限仅限于特定角色,则他们看到的密钥详情中 显示 (Show)、复制 (Copy)、重新生成 (Regenerate) 和 新建密钥 (New key) 按钮将处于禁用状态。您也可以完全跳过客户的密钥,直接使用您的代理机构密钥加上
sub_account_id来调用 API。
在哪里查找: API Key 是 Settings → Integrations 下的一个独立部分,与 Webhooks 分开。如果指南或同事告诉您在“Webhooks”下查找密钥,请查看旁边的部分。
作用域密钥:针对特定任务的额外密钥
您的主密钥拥有所有权限,因此不适合分发给报告、客户仪表板或独立的沙盒及开发环境使用。为此,请在“您的密钥”下方的“API 密钥”部分中的“作用域密钥”卡片中创建作用域密钥:
- 点击 New key。
- 为其输入一个稍后能识别的 Name,例如“Sandbox”或“Acme client dashboard”。
- 在 What it can see 下,仅勾选其需要的区域。最常用的区域会列在前面;打开 More areas 以查看所有其他区域(坐席、常见问题解答、知识库、聊天小部件、入口点、Webhook 等),并配有搜索框。每个区域都对应 API 参考文档的一个部分,因此请勾选您的工具所调用的部分。向联系人发送消息在每个渠道上都属于 Messages,包括 WhatsApp Web。代理机构:SubAccounts 涵盖客户账户端点(列出和管理您的子账户),Snapshots 涵盖快照;两者都与 Agency 分开,因此请勾选您的工具所调用的那个。
- 在 What it can do 下,除非工具必须进行更改,否则请保留 Read only。具有更改权限的密钥可以发送消息并编辑您的设置。
- 代理机构:在 Client accounts 下,选择 Only this account 或 This account and all client accounts(您管理的所有客户账户,包括您以后添加的账户)。传递
sub_account_id的工具需要选择后者。 - (可选)设置 Requests per minute(其自身的限制,因此它永远不会拖慢您的其他集成)和 Expires on 日期。
- 点击 Create key 并立即复制它。作用域密钥仅显示一次;如果您丢失了密钥,请撤销它并创建一个新的。
您可以根据需要创建任意数量的密钥。列表中的每个密钥都会显示其上次使用的时间。Edit 可以更改密钥的名称、区域、只读设置和客户账户,而无需更改密钥本身,因此您连接的任何内容都不需要新密钥。Revoke key 会立即停止其工作。创建、编辑或撤销作用域密钥绝不会影响您的主密钥。包括仅限于特定客户账户列表的密钥在内的完整选项,请参阅 API 参考文档的 API keys 页面。
当您通过登录连接 Claude 或 ChatGPT 等 AI 助手时,它会出现在与该应用同名的列表中(例如 Claude (已登录)),并拥有对您账户的完全访问权限。撤销该权限即可断开与该应用的连接。请参阅 连接 AI 助手 (MCP)。
基础 URL
所有 API 请求均使用以下基础网络地址:
https://api.dmchamp.com/v1/
身份验证
每个请求都必须包含您的 API 密钥,以便平台识别您的身份。最简单的方法是将其添加到网址末尾:
https://api.dmchamp.com/v1/contacts?apiKey=YOUR_API_KEY
您也可以将密钥作为请求标头发送,而不是放在 URL 中(建议在生产环境中使用,这样密钥就不会出现在服务器日志中):
X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
所有请求都必须使用安全连接 (HTTPS)。不安全的 (HTTP) 请求将被拒绝。
正在寻找完整的开发者指南? 本页面是涵盖最常见操作的快速入门。如需完整的、分步指南(包含每个资源以及 cURL、JavaScript 和 Python 示例),请参阅 API 入门 和 API 参考。
常见 API 操作
创建联系人
请求:
POST https://api.dmchamp.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"firstName": "Jane",
"lastName": "Smith",
"phoneNumber": "+15551234567",
"email": "[email protected]"
}
必填字段: 创建联系人时需要 phoneNumber(带国家/地区代码),电子邮件则是可选的。唯一的例外是电子邮件联系人:发送 "channel": "email" 并提供有效的 email,则无需电话号码(这需要已连接的邮箱)。
响应:
{
"success": true,
"data": {
"message": "Successfully created new contact",
"contactId": "abc123xyz",
"listsAdded": []
}
}
保存 data.contactId ——您在调用“将联系人添加到列表”时需要用到它。
**注意:**如果具有相同电话号码的联系人已存在,API 不会创建第二个联系人。它会返回 { "success": false, "error_code": 409, "contactId": "..." },并在 contactId(以及 data.contactId)中包含现有联系人的 ID,以便您可以继续使用该联系人。
将联系人添加到列表
POST https://api.dmchamp.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"contactId": "abc123xyz",
"listId": "YOUR_LIST_ID"
}
在应用程序的 联系人 → 列表 下,通过列表行菜单(复制列表 ID)查找列表的 ID。
更新联系人
PUT https://api.dmchamp.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"customFields": { "company": "Acme Inc" }
}
仅会更改您包含的字段。这也是导入后批量加载自定义字段值的方法——请参阅 自定义字段、潜在客户资料和备注。详细信息请参阅 联系人 API。
发送消息(自定义渠道)
POST https://api.dmchamp.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"customData": {
"fromId": "external-contact-id",
"customChannel": "my-channel",
"body": "Hello Jane! Your order has been shipped.",
"campaignId": "optional-campaign-id",
"firstName": "Jane",
"lastName": "Smith"
}
}
| 字段 | 必填 | 描述 |
|---|---|---|
customData.fromId |
是 | 联系人在您平台上的 ID |
customData.customChannel |
是 | 您的自定义渠道名称 |
customData.body |
是 | 要发送的消息文本 |
customData.campaignId |
否 | 旧版:通过 ID 将联系人放入旧活动中。它不接受 AI 代理 ID |
customData.firstName |
否 | 联系人的名字(用于创建新联系人时) |
customData.lastName |
否 | 联系人的姓氏 |
customData.email |
否 | 联系人的电子邮件地址 |
**注意:**此端点仅用于自定义渠道消息。对于 WhatsApp、SMS、Instagram 和 Messenger,消息通过“广播”和“AI 智能体”发送。
接收传入消息(自定义渠道)
接收来自外部系统的消息作为自定义渠道。这就是像 GoHighLevel 这样的集成将消息发送到 DM Champ 的方式。有关完整详细信息,请参阅 自定义渠道。
POST https://api.dmchamp.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json
{
"customData": {
"messageSid": "unique-message-id",
"fromId": "external-contact-id",
"toId": "your-user-id",
"body": "Customer's message here",
"channel": "custom",
"status": "received"
},
"messageType": "text"
}
| 字段 | 必填 | 说明 |
|---|---|---|
customData.messageSid |
是 | 此消息的唯一 ID(防止重复)。您也可以使用 customData.id。 |
customData.fromId |
是 | 您外部系统中的发送者 ID。 |
customData.toId |
是 | 您的业务标识符。 |
customData.body |
是 | 消息文本。 |
customData.channel |
否 | 来源标签(例如 "email"、"livechat"、"custom")。 |
customData.status |
否 | 消息状态。默认为 "received"。 |
messageType |
否 | 文本消息使用 "text",表情符号反应使用 "reaction"。 |
可用操作概览
| 操作 | 方法 | 地址 | 说明 |
|---|---|---|---|
| 创建联系人 | POST |
/contacts |
向您的账户添加新联系人 |
| 获取联系人详情 | GET |
/contacts?phoneNumber=X 或 /contacts?email=X |
通过电话号码或电子邮件查找联系人 |
| 更新联系人 | PUT |
/contacts/{contactId} |
更新现有联系人上的任何字段 |
| 将联系人添加到列表 | POST |
/contacts/lists |
将现有联系人添加到特定列表 |
| 发送消息 | POST |
/send_custom_channel_message |
通过自定义渠道发送消息 |
| 接收消息 | POST |
/incoming_custom_channel_message |
接收来自外部系统的消息 |
速率限制
API 强制执行速率限制以确保平台稳定性。超出限制将返回 429 Too Many Requests — 请停止请求并在响应头中指示的时间后重试。对于大容量使用场景(批量导入),请使用内置的 导入功能 或发送电子邮件至 [email protected] 获取指导。
最佳实践
- 安全存储您的 API 密钥 — 使用密码管理器或服务器端配置,切勿将其放在浏览器访问者可以读取的客户端代码中。
- 电话号码中始终包含国家/地区代码(美国为
+1,英国为+44,荷兰为+31)。 - 妥善处理错误 — 检查状态码并阅读返回的任何错误消息。
- 处理重复项 — 重复的电话号码会返回
{ "success": false, "error_code": 409 }而不是新联系人,并在contactId中提供现有联系人的 ID。 - 在运行批量操作之前,先使用小数据集进行测试。
错误响应
错误返回时会包含 success: false 和一条通俗易懂的 error 消息。许多端点还会添加一个代码(数字 error_code 或文本 code);每个端点的错误信息均列在 API 参考 中。
{
"success": false,
"error": "Invalid phone number. Ensure it includes a valid country code and is in the correct format."
}
| 状态码 | 含义 |
|---|---|
200 |
成功 |
201 |
资源已创建 |
400 |
错误请求 — 请检查您的参数 |
401 |
未授权 — API 密钥无效或缺失 |
403 |
禁止访问 — 您的套餐不包含 API 访问权限,或您缺乏相应权限 |
404 |
资源未找到 |
429 |
超出速率限制 |
500 |
服务器错误 — 如果问题持续存在,请发送电子邮件至 [email protected] |
后续步骤
- Webhooks — 从应用程序接收实时通知(与您的 API 密钥分开的部分)。
- 连接 AI 助手 (MCP) — 使用相同的 API 密钥让 Claude 操作您的账户。
- Facebook 潜在客户表单 — 在“广告”页面连接潜在客户表单,或通过自动化平台发送潜在客户。
- GoHighLevel 集成 — 一个完整的双向 API 集成示例。