XSwitch API 使用指南

XSwitch 提供 REST API、WebSocket API、AI-API、XCC API 等多种 API，什么时候该用哪种 API 呢？

从逻辑功能上来说，XSwitch 提供两种 API：

• 操作数据库增删改查（CURD）的 API，一般使用 REST API。
• 呼叫控制 API，可以使用多种 API。

对呼叫控制 API 来讲，从操作范围来讲，XSwitch 提供的 API 有：

• 控制所有呼叫和会议的 API
• 控制单个呼叫或会议的 API

从某种意义上说，还有两种 API：

• 操作静态数据的 API
• 操作运行时动态数据的 API

下面对各种 API 的基本特性和操作范围做一个简单介绍。

REST API 底层使用 HTTP 协议，用于操作数据库的增删改查（CURD），一般是操作静态数据。比如创建一个用户、分机、路由等。这些数据创建后，一般都会存储在数据库中。

REST API 也可以用于获取登录 Token 等。

REST API 可以在后端使用 Java、Go 等语言调用，也可以在浏览器前端调用。对于一些高权限、风险高的 API（比如关机、重启等），只允许从后端调用。

REST API 也可以控制呼叫和会议。但本质上，由于 REST API 是基于 HTTP 的，而 HTTP 是一个单向的协议，只允许客户端（如浏览器）请求服务器，而服务器不能主动反推消息。所以，REST API 适用于比如发起和挂断一路通话，加入一个会议等，但是不适合监听一个呼叫的进展（在呼叫中的振铃、接听、挂断等状态更新）。

REST API 也可以对一些纯媒体模拟提供简单的信令支持，如微信小程序、WebRTC、声网 Agora、腾讯 TRTC 等。典型的，WebRTC 的 WHIP 协议就是基于 HTTP 的，XSWitch 支持 WHIP、WHAP 和 WHXP（WHXP 是 XSwitch 对 WHIP 和 WHAP 的扩展）。

由于 REST API 使用比较简单，所有 Web 开发程序员都会用，而且没有复杂的状态机，因而使用也非常广泛。

理论上，REST API 可以比较方便地支持缓存，比如一些访问频繁但更新不频繁的数据，可以通过缓存减少服务器和数据库的压力。

参见XSwitch REST API。

为了支持双向通信，XSwitch 提供了 WebSocket API。WebSocket API 适用于浏览器端，比如在呼叫中心场景中，需要签入、签出等操作，又需要实时监听呼叫事件，以便在呼叫中心界面上显示呼叫状态，进行来电弹屏等。

有一些 API，如签入、签出等，只是一些动作，因而，担任了 WebSocket 和 REST 两种方式。而如果需要订阅和接收呼叫进展事件，则需要使用 WebSocket API。

此外，WebRTC、微信小程序、声网 Agora、腾讯 TRTC 等只是媒体层的协议，它们与 XSwitch 进行双向通信的信令在浏览器和 App 端也是通过 WebSocket 来实现的。

参见：

• XSwitch RTC 开发文档
• 呼叫中心 API

XCC API 基于 NATS 消息队列实现，具有 XSwitch 完整的运行时控制能力，可以动态提供配置、动态控制通话行为等，真正做到了“通信层和控制层分离”。

XCC API 也提供微信小程序、WebRTC、声网 Agora、腾讯 TRTC 等的信令支持。

NATS 是使用 Go 语言编写的消息队列，性能非常高，而且通过 NATS，完成了 XSwitch 与控制层的解耦——重启 XSwitch 并不需要控制侧重启或重连！NATS 具有各种语言的客户端（如 C、Java、Go、Python、C#等），因此你可以用任何你擅长的语言与 XSwitch 集成。

XCC API 除了可以完全控制 XSwitch 运行时状态，还可以管理庞大的 XSwitch 集群，比如上千个 XSwitch 节点的集群，支持弹性伸缩，XSwitch 热更新等。

任何集成，只要 XCC API 能够完成的，我们都推荐优先选择 XCC API。

详见：XCC API。

XSwitch 基于 FreeSWITCH 开发，FreeSWITCH 底层的 ESL 接口也完整支持，如果你已经针对 FreeSWITCH 开发了 ESL 的程序，可以没有任何困难地对接 XSwitch。

XCC API 也基本可以完全代替 ESL。

HTTAPI 是 FreeSWITCH 原生的接口，它通过 HTTP 协议实现双向控制，使用 Web 程序员可以方便地控制呼叫流程。下面是几个典型的应用场景：

当一个 SIP 呼叫到达 XSwitch 时，XSwitch 会发送一个 HTTP 请求到你的 Web 程序，你的程序返回一个 XML 文档，告诉 XSwitch 下一步要干什么，如放音（或 TTS），接收 DTMF、进行语音识别（ASR）等。当 XSwitch 获取到用户输入后（如 DTMF 或通过 ASR 检测到语音），会再发起一次请求到你的 Web 程序，周而复始。

HTTP 协议是单向的，在整个呼叫存续过程中，永远只是 XSwitch 做为 HTTP 客户端去请求你的 Web 服务器。但是，当 XSwitch 在执行通话过程中，如果你的 App 想对呼叫进行主动控制（如挂机、转接等），你就需要向 XSwitch 发送 HTTP 请求，这时你的 App 作为 HTTP 客户端，XSwitch 作为 HTTP 服务器。这种模式也适用于你的 App 客户端主动控制 XSwitch 发起外呼的场景。

HTTAPI 的优点是对 Web 程序员友好，缺点也很明显：HTTP 不是长连接，每次交互都需要建立和断开连接，与 WebSocket 相比，后者一般在一次通话过程中只需要保持一个连接（甚至一个 WebSocket 连接也能控制所有通话）。

HTTAPI 的协议文本是基于 XML 格式封装的。XSwitch VIP 用户可以向我们申请 HTTAPI 文档。

AI-API 是 HTTAPI 的一个翻版，把 XML 变成了 JSON，并增加了一些新的 API 和交互。

AI-API 的外呼功能比较强大，App 可以通过直接 POST 一个 JSON 文档发起一个呼叫，执行一系列流程。

此外、AI-API 也支持简单的状态通知（在来电、挂机、话单时对外 POST HTTP 消息）。

如果你是一个 Web 程序员，可以选择使用 AI-API。但 AI-API 的功能不比 XCC API 丰富。

详见：AI-API。

XSwitch 的后台 REST API 接口和很多呼叫控制流程都是基于 Lua 语言开发。XSwitch 团队在 Lua 语言和模块上投入了很多，Lua 脚本可以在 XSwitch 内部写很多控制逻辑，对于 XSwitch VIP 用户，我们也支持通过 Lua 脚本扩展 XSwitch 的能力，如自动外呼、ASR 识别等。

XSwitch 核心设计理念是高度可定制，你可以根据你的需要和团队的开发能力定制 XSwitch，如：

• 通过上述各种 API 接口定制
• 通过后台 Lua 脚本定制后台 API 和呼叫流程
• 可以植入 C 语言写的扩展模块扩展 XSwitch 各种功能
• 在前端可以通过 JS 插件扩展前端界面和功能、修改风格等
• 可以通过 REST API 访问数据库所有表或者直连数据库（PostgreSQL）

目前，仅对 XSwitch VIP 用户和 XSwitch 企业版用户提供定制能力。

画重点：这么多 API，我应该先用哪一种呢？

简单来说，这个问题没有统一答案。之所有有这么多 API 就是为了适应不同的场景和需求，你要根据你的应用场景和团队开发能力选择合适的 API。

• 在呼叫控制上，我们推荐优先考虑 XCC API，因为它稳定、强大、易用，而且可以几乎无限地弹性伸缩。
• XCC API 目前没有数据操作接口，因此，如果你需要增删改查操作数据库中的数据，还需要 REST API。
• 如果你是一个 Web 程序员，可以选择 AI-API。
• 如果你不想开发后端，只想在浏览器端主动集成电话条、点击拨号等简单场景，可以使用 REST API 或基于 WebSocket 的 API。

下面是一些常见的 API 使用场景。

在 Web 界面上点击一个电话号码，自动拨打一个电话。有以下几种实现方式：

首先你需要自己有个 SIP 电话，不管是硬件电话或者是软电话，该电话有个号码（分机号），已经注册到 XSwitch 上。当前端调用 API 发起一个呼叫时，至少包含两个参数，你的分机号和要拨打的号码（被叫号码）。XSwitch 会先呼叫你的分机，你在分机上应答后，XSwitch 再呼叫被叫号码。

回呼可以使用 REST API 实现（POST /api/channels），但看不到呼叫进展。但无论如何它比你手工拨号要快。

回呼也可以使用 WebSocket API 实现，使用呼叫中心 API，你需要把分机号做为一个坐席分机签入到一个呼叫队列中。

回呼也可以使用 AI-API 实现，你不应该在浏览器端直接调用 AI-API（不安全），而是应该把你的外呼请求发送到你的 Web 服务器上，你的 Web 服务器再调用 AI-API 发起呼叫请求，可以调用（ai.dial接口）。

回呼也可以使用 XCC API 实现，同样你需要在 Web 后台中调用 XCC API 而不应该在浏览器前端直接调用。

如果我的浏览器支持 WebRTC，也可以直接使用 WebRTC 发起呼叫。WebRTC 也需要一个分机号，但不需要硬件电话或软电话，因为 WebRTC 就是一个软电话。

参见：如何在 XSwitch 中使用 WebRTC。

使用呼叫中心 API 以及 XRTC API。

使用 XCC 接口可以接收话单，订阅cn.xswitch.ctrl.cdr事件。

使用 AI-API 接口可以通过 HTTP 方式推送话单。

XSwitch 会往数据库中写入话单，如果话单推送异常（如你的 Web 服务器不能正常响应、或者 XCC 接收端崩溃等），可以从 XSwitch 数据库中获取话单。

可以通过 REST API 查询话单，或直联数据库获取话单。

XSwitch 可以针对一些预设的场景自动录音，也可以在以上各种 API 控制下按需录音。

XSwitch 可以在推送和话单事件中包含录音的 URL，App 收到后可以主动下载，也可以直接从后面通过 FTP、sFTP 等方式访问。

XSwitch 的话单上也有关联的录音路径。

XSwitch 内部会将录音元数据（文件名、文件格式、文件大小等）存放到“媒体文件”数据库表中，可以与话单关联查询。

云盘用户（如阿里 OSS 和华为 OBS 等），可以直接挂载云盘，将录音实时录到云盘上。

私有化部署场景可以直接挂载 NAS，NFS 等共享。

此外，也可以写一个脚本（Shell、Python 等）对录音进行一系列处理，如：

• 通过监测硬盘 iNotify 事件，在文件 CLOSE 的时候开始转换（如转成 mp3）并上传云盘
• 通过接收 NATS 消息，在收到话单时获取录音文件路径并自动上传
• 通过一些 Serverless、云函数等方式，实现录音自动转码、上传云盘等

XSwitch 对 VoLTE 和 5GNR 的支持上在底层实现在，在呼叫流程交互时往往根据需要调整使用不同的参数（如在通话中音视频升降级、分辨率调整、码率调整等），建议使用 XCC API 和 Lua API 以获取最灵活的控制功能和权限。

XSwitch 本身是一个 MCU，支持普通终端、各种 MCU、各种 SFU 的对接。可以通过 XCC API 和 Lua 接口控制各种呼叫流程。

XSwich 支持大规模会议串联（多个会议串联或级联），需要单独的管控组件（cMan，Conference Manager），使用 XCC API 实现。可以通过 NATS 协议或 WebSocket 协议调用。两者的区别是，XCC NATS 协议本身权限比较高，在后台接入完全可信任，可以控制整个集群和所有会议，而 WebSocket 协议一般只适用于管理一个或几个少数的会议。

XSwitch 提供了多种 API，就是为了给大家各种灵活的功能和选择。但我们深知“过犹不及”，多了也并不一定是好事。所以，如果您看了本文后对我们的 API 还是感到困惑，可以联系我们。我们会尽量帮助您选择最适合您的 API，帮您最高效地解决问题。