DM Champ Docs

API 访问

API(应用程序编程接口)是不同软件系统之间进行通信的一种方式。DM Champ API 允许您(或您的开发人员)自动创建联系人、发送消息、管理列表以及从自定义渠道接收传入消息——所有这些都无需使用仪表板。

Prefer to see it? Click through the whole flow:

为什么要使用 API? 如果您想将应用程序连接到没有内置集成的工具,或者需要大规模自动化重复性任务,API 就是实现这一目标的方法。

注意: 本页面性质偏向技术。如果您是企业主而非开发人员,建议您将此页面分享给您的技术团队或自由职业开发人员。


生成您的 API 密钥

注意: API 访问是符合条件的套餐中提供的一项付费功能。如果您的套餐不包含此功能,API 请求将被拒绝并返回 403 响应。如果不确定是否启用了 API 访问,请检查您的套餐或联系支持团队。

  1. 在左侧边栏中,点击 Settings(齿轮图标)。
  2. 在 Settings 侧边栏的 Integrations 组下,点击 API Key。
设置页面,显示了分组的左侧导航栏

API Key 位于“设置”中的“集成”组下,与 Webhooks 和 Booking & Calendar 并列。

  1. 如果您还没有密钥,请点击 Generate API key。
  2. 如果您已经拥有一个密钥,它将以掩码形式显示在 Your key 下方。如果您的密钥支持,请点击 Show 以显示它,然后点击 Copy 进行复制——您将看到一条确认提示。
  3. 请将密钥存放在安全的地方——每次 API 请求都需要用到它。
API Key 设置部分,显示了一个已遮盖的密钥和重新生成卡片

您的密钥显示为已遮盖状态。旧密钥可能会显示“无法显示您的密钥”,而不是“显示/复制”——密钥仍然有效,只是您无法在不重新生成的情况下再次查看明文。重新生成卡片位于同一部分的下方,而不是单独的页面。

注意: 部分账户会看到“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 密钥”部分中的“作用域密钥”卡片中创建作用域密钥:

  1. 点击 New key。
  2. 为其输入一个稍后能识别的 Name,例如“Sandbox”或“Acme client dashboard”。
  3. 在 What it can see 下,仅勾选其需要的区域。最常用的区域会列在前面;打开 More areas 以查看所有其他区域(坐席、常见问题解答、知识库、聊天小部件、入口点、Webhook 等),并配有搜索框。每个区域都对应 API 参考文档的一个部分,因此请勾选您的工具所调用的部分。向联系人发送消息在每个渠道上都属于 Messages,包括 WhatsApp Web。代理机构:SubAccounts 涵盖客户账户端点(列出和管理您的子账户),Snapshots 涵盖快照;两者都与 Agency 分开,因此请勾选您的工具所调用的那个。
  4. 在 What it can do 下,除非工具必须进行更改,否则请保留 Read only。具有更改权限的密钥可以发送消息并编辑您的设置。
  5. 代理机构:在 Client accounts 下,选择 Only this account 或 This account and all client accounts(您管理的所有客户账户,包括您以后添加的账户)。传递 sub_account_id 的工具需要选择后者。
  6. (可选)设置 Requests per minute(其自身的限制,因此它永远不会拖慢您的其他集成)和 Expires on 日期。
  7. 点击 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]

后续步骤