回拨 API

回调通话是指最终用户请求的通话。借助回调通话 API，您可以以编程方式安排回调通话和取消已安排的通话。借助这些功能，您可以创建应用，让最终用户可以从您指定的队列请求回调通话。最终用户还可以取消他们之前安排的通话。如需了解如何使用 回调通话 API 进行身份验证，请参阅基本身份验证。

使用回调通话 API

您可以使用回调通话 API 安排回调通话和取消已安排的通话。

安排通话

如果您的实例与 Salesforce 集成，请检查设置 > 运营管理 > CRM 记录创建详情 下的在发起 API 安排的通话时关闭记录选项 设置。如果选择了不检查记录状态，则安排请求会被 拒绝，并返回 422。这不适用于 Zendesk 或 ServiceNow。

如需安排通话，请调用 POST https://<subdomain>.<domain>/apps/api/v1/calls ，并添加类似于以下内容的请求正文：

{
    "call_type": "ScheduledCall",
    "menu_id": 12345,
    "end_user_number": "+18005550100",
    "scheduled_at": "2025-09-02T14:30:00Z"
}

如果请求成功，则会返回通话对象，包括通话 ID。

取消已安排的通话

如需取消已安排的通话，请调用 PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/{id}/cancel。指定要取消的通话的 ID。

如果请求成功，则会返回有关已取消通话的信息。

取消多个已安排的通话

如需取消多个已安排的通话，请调用 PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel。添加一个请求正文，其中包含要取消的通话的 call_ids 数组（以整数形式表示）。如果值不是数组，或者包含非整数条目，则会被拒绝，并返回 400。

请参阅以下代码示例：

{
    "call_ids": [123, 456, 789]
}

如果请求成功，则会返回一个响应，其中包含一个响应标头，该标头包含用于检查取消状态的 Location 网址。

将回调通话与 CRM 搭配使用

您可以将回调通话 API 与 Salesforce、Zendesk 和 ServiceNow CRM 集成搭配使用。

一般回调行为

如果您使用的是任何受支持的 CRM（Salesforce、Zendesk 或 ServiceNow），则以下条件会影响已安排的回调行为：

  • 记录已打开且已有有效的已安排通话：如果工单 ID 查找表明记录已打开且已有有效的 已安排通话，则不会安排该通话。以下注释会附加 到 CRM 记录：A scheduled call was not created because the record already has an active scheduled call。

  • 无法访问 CRM：如果工单 ID 查找表明 CRM 无法访问，则会取消该通话。以下注释会附加 到 CRM 记录：A scheduled call was canceled because the CRM was unreachable。

关闭记录时的回调行为

对于关闭的记录，回调通话的处理方式因您使用的 CRM 而异：

  • Zendesk 和 ServiceNow 用户：如果工单 ID 查找表明 记录已关闭，则不会安排该通话。以下注释会 附加到 CRM 记录：A scheduled call was not created because the record is closed。

  • Salesforce 用户： 如需配置实例如何处理关闭记录的已安排通话，请参阅将回调通话与 Salesforce搭配使用。

将回调通话与 Salesforce 搭配使用

如果您已将 CCAI Platform 与 Salesforce 集成，则可以配置实例如何处理关闭记录的已安排通话。以下是 Salesforce 集成的配置选项：

不检查记录状态

您可以配置 CCAI Platform，使其在进行已安排的通话之前不检查记录状态。如果选择了此选项，则通过回调通话 API 安排通话的请求会被拒绝，并返回 422。

如需将 CCAI Platform 配置为不检查记录状态，请按以下步骤操作：

  1. 在 CCAI Platform 门户中，依次点击设置 > 运营 管理。如果您没有看到设置 菜单，请点击 菜单。

  2. 依次前往 CRM 记录创建详情 > 在发起 API 安排的通话时关闭记录选项。

  3. 选择不检查记录状态。始终发起 API 安排的通话 。

  4. 点击保存常规 。

检查记录状态并重新打开已关闭的记录

您可以配置 CCAI Platform，使其在进行已安排的通话之前检查记录状态，并重新打开已关闭的记录。如果采用此配置，当记录状态为“已关闭”时，系统会执行以下操作：

  • 系统会按计划进行通话。

  • 系统会重新打开记录。

  • 以下注释会附加到 CRM 记录：The record was reopened at the time of a scheduled call。

如需将 CCAI Platform 配置为检查记录状态并重新打开已关闭的记录，请按以下步骤操作：

  1. 在 CCAI Platform 门户中，依次点击设置 > 运营 管理。如果您没有看到设置 菜单，请点击 菜单。

  2. 依次前往 CRM 记录创建详情 > 在发起 API 安排的通话时关闭记录选项。

  3. 选择检查记录状态。如果记录已关闭 > 重新打开记录。

  4. 点击保存常规 。

检查记录状态并取消已关闭记录的已安排通话

您可以配置 CCAI Platform，使其在进行已安排的通话之前检查记录状态，并取消已关闭记录的已安排通话。 如果采用此配置，当记录状态为“已关闭”时，系统会执行以下操作：

  • 系统会取消已安排的通话。

  • 以下注释会附加到 CRM 记录：A scheduled call was canceled because the record is closed。

如需将 CCAI Platform 配置为检查记录状态并取消已关闭记录的已安排通话，请按以下步骤操作：

  1. 在 CCAI Platform 门户中，依次点击设置 > 运营 管理。如果您没有看到设置 菜单，请点击 菜单。

  2. 依次前往 CRM 记录创建详情 > 在发起 API 安排的通话时关闭记录选项。

  3. 选择检查记录状态。如果记录已关闭 > 取消已安排的通话。

  4. 点击保存常规 。