3CX 呼叫控制 API

什么是呼叫控制 API？

3CX 呼叫控制 API 是一个简单而强大的工具，它允许以编程方式管理呼叫。利用 API，您现在可以将 PBX 呼叫功能直接集成到您的第 3 方应用程序中。您可以构建的应用程序示例包括：

  • 外部呼叫控制： 从您自己的应用程序以编程方式发起、接听、转接、终止呼叫。
  • CRM 集成： 自动从 CRM 系统发起呼叫、记录呼叫详细信息并简化客户交互。
  • outbound campaign： 设置并连接您自己的外呼营销活动脚本，以实现复杂的呼叫定位策略。
  • 人工智能集成： 使用 Whisper API 等现代语言模型来处理传入的用户语音数据。
  • 咨询服务自动化： 管理传入的支持呼叫，将其路由到适当的代理，并跟踪呼叫指标。

配置 API 集成

从 3CX Web 客户端的管理控制台，转至 集成 > API:

  1. 按 添加 按钮创建新的客户端应用程序。
  2. 指定 客户端 ID （ID用于访问路由指向，这也是授权所必需的）。
  3. 如果使用呼叫控制 API ，请选中此应用程序的3CX调用控制API访问复选框。
  4. （可选）指定路由指向的 DID 号码。
  5. （可选）指定您想要使用 API 监控的其他分机。
  6. 成功创建新的 API 实例后，您将收到第三方应用程序的 API 密钥。该密钥只会显示一次，因此请务必保存以供将来使用。

就是这样！您已成功完成 PBX 配置。

请注意： 您必须拥有 3CX Enterprise 许可证才能使用 3CX 呼叫控制。

它是如何运作的

RESTful API

呼叫控制API提供了既简单又适用于执行呼叫操作的端点。这些端点的设计是安全的，不会干扰核心PBX功能或造成任何损坏。

有关更多信息，请参阅“ 3CX 呼叫控制 API 端点规范”

WebSocket

PBX 呼叫控制 API 中的 WebSocket 集成是外部应用程序和 PBX 服务器之间的一个强大的实时通信通道。它增强了应用程序和 PBX 间的交互，特别是对于事件驱动的呼叫控制和状态管理。

同时使用 WebSocket 和 HTTP (GET/POST)

灵活沟通： WebSocket不会取代传统的HTTP方法。相反，它通过充当活动交付的专用渠道来补充它们。虽然应用程序仍然可以对特定数据或操作使用GET和POST请求，但WebSocket针对接收实时事件进行了优化。这种灵活性允许应用程序根据用例选择最佳方法，例如使用WebSocket进行实时更新，使用HTTP进行直接请求。

高效的仅事件通道： 鉴于WebSocket对消息大小的限制，WebSocket可以仅用于事件传递，确保在只传输必要的实时更新而没有大量消息的情况下进行高效通信。

技术概述

PBX 呼叫控制 API 中的 WebSocket 通信遵循请求和响应的结构化格式，确保交互的清晰度和一致性：

应用程序请求（WebSocketRequest）：

  • 应用程序可以通过发送 WebSocketRequest 消息通过 WebSocket 发送实时请求。
  • 每个请求包括：
  • RequestID： 外部应用程序提供的用于跟踪响应的 ID。
  • Path： API路径（类似于HTTP GET请求中使用的路径），例如/callcontrol， /callcontrol/{dn} 或 /callcontrol/{dn}/participants/{id}。
  • RequestData： 这是呼叫控制操作所必需的，例如 makecall 或者 divert 对于 GET 请求来说是可选的。

服务器响应（WebSocketResponse）：

  • 服务器响应一个 WebSocket响应，其中包括：
  • RequestID： 请求的 ID，确保外部应用程序可以将响应与请求相匹配。
  • Path： 请求的路径（例如， /callcontrol/100）。
  • StatusCode： HTTP状态码，表示请求成功或失败。
  • Response： 响应的内容，根据请求路径而变化。

WebSocket 事件（通知通道）

在 PBX 呼叫控制 API 中，服务器通过 WebSocket 发送事件。此事件是 ExtenlCallFlowEventTypes 的一部分。响应系统，旨在以结构化和一致的方式向外部应用程序传达响应。以下是对其工作原理的解释：

使用 ExternalCallFlowAppHookEvent 的服务器响应

当被监控的 DNS 状态发生变化时，服务器最终会通过 WebSocket 向外部应用程序发送一个事件作为响应。事件具有以下类型：

ExternalCallFlowAppHookEvent {

    EventType=0;

    Entity=<path as was specified in the request>;

    AttachedData=<WebSocketResponse>;

}

字段说明：

  1. EventType=5（ENUM）：EventType 字段是一个枚举值（ENOM），表示与状态相关的事件类型。它有助于外部应用程序了解事件的性质并做出相应的响应。

Enum Number

描述

0

Upsert

实体已添加或更新

1

Remove

该实体已被删除

2

DTMFstring

远端用户是 DTMF 提供者 。

注：DTMFString 事件是媒体控制功能的一部分。仅当 DTMF 事件属于应用程序本身时（即，在应用程序 ID 与其远端用户之间），应用程序才能接收 DTMF 事件。

4

Response

对通过 WebSocket 发送的请求的响应

  1. 实体：实体表示应用程序最初发出的请求的特定路径。此路径与原始 WebSocket 请求中指定的路径相同（例如，/callcontrol、/callcontrol/{dn}或/callcontrol/{dn}/participants）。

这有助于外部应用程序了解响应与 API 的哪一部分相关。

  1. AttachedData: AttachededData 包含来自服务器的实际 WebSocketResponse 。此对象包括请求 ID 、HTTP 状态代码和响应数据等关键细节。

外部应用示例

有关使用PBX呼叫控制API设置外部呼叫流应用程序的详细步骤，请参阅“外部呼叫流示例入门”文档。它包括：

  • PBX配置：在3CX Web客户端中添加客户端应用程序、配置API和获取API密钥的说明。
  • 外部Web应用程序设置：设置外部应用程序的步骤，包括安装Node.js、下载必要的文件、运行示例（IVR、Outbound Campaign、Dialer）以及在本地环境中配置应用程序。

本文档还介绍了运行呼叫控制的基本示例，以及设置自定义 IVR、Dialer和Outbound Campaign以与 3CX PBX 系统集成。

另请参阅

最后更新

本文档最后更新日期为 2025 年 3 月 12 日

https://www.3cx.cn/docs/call-control-api/