回拨 API

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

使用回拨 API

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

预约电话咨询

如需安排通话，请调用 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。

如果请求成功，则会返回一个 200 OK，其中包含更新后的通话对象。当通话正在等待其预定时间 或正在进入或在队列中等待时，通话 对象的 status 为 cancelled；当您取消已进行首次拨号尝试的 活跃虚拟客服回调时，通话对象的 为 completed。 如果通话已被取消，请求会返回 204 No Content，且正文为空。如果请求取消的调用已因取消以外的原因而失败，或者处于无法取消的状态，则会返回 400。

取消多个已安排的通话

如需取消多个预定调用，请调用 PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel。添加一个请求正文，其中包含要取消的通话的通话 ID 的 call_ids 数组。

请参阅以下代码示例：

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

成功的请求会返回 202 Accepted，其中包含指向作业资源的 Location 响应标头，您可以轮询该资源以了解作业是否完成。202 Accepted 响应并不意味着每个调用都已取消；请按照 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，使其在进行预约通话之前不检查记录状态。采用此配置后，无论记录是打开还是关闭，系统都会按计划拨打电话。

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

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

  2. 依次前往 CRM Record Creation Details（CRM 记录创建详情）> Closed record options when initiating an API-scheduled call（发起 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 Record Creation Details（CRM 记录创建详情）> Closed record options when initiating an API-scheduled call（发起 API 安排的通话时的已关闭记录选项）。

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

  4. 点击保存常规设置。

检查记录状态，并取消已关闭记录的预定通话

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

  • 预约的通话已取消。

  • 以下评论已附加到 CRM 记录：A scheduled call was canceled because the record is closed。

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

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

  2. 依次前往 CRM Record Creation Details（CRM 记录创建详情）> Closed record options when initiating an API-scheduled call（发起 API 安排的通话时的已关闭记录选项）。

  3. 选择查看记录状态。如果记录已关闭 > 取消预约的通话。

  4. 点击保存常规设置。