XSwitch 集成架构

一般来说，我们支持两种集成架构，后端集成和前端集成。当然，这两种方式又可以演变出一些混合方式，总体集成结构如下图：

一般来说，我们推荐开发者使用后端集成方式。开发者后台的服务器端程序与 XSwitch 交互，而前端浏览器的登录鉴权全部由开发者解决，这种方式开发者有极大自由设置登录及安全策略，而无须考虑 XSwitch 侧的情况。

如下图。XSwitch 侧负责电话、中继等语音有关的都在平台侧，而开发者一侧有服务端和浏览器端。客户通过浏览器与自己的后端服务交互。XSwitch 只与后端服务交互。消息中间件（Message Queue、Redis、DB 等），如果需要的话，可以放在 XSwitch 侧，也可以放在开发者侧。

这样方式比较灵活，支持任何开发语言。但开发者需要开发自己的方式与浏览器交互（消息获取和消息通知机制等）。

后端集成包括：

• XSwitch REST API 接口
• XSwitch XCC API 接口
• XSwitch AI API 接口
• 各种 API 示例代码

注意：XCC 集成是纯后端集成，是我们推荐的集成方式。XCC 接口可以完全控制 XSwitch，实时获取和控制 XSwitch 状态，功能非常强大。但正因为其强大，所以不适合直接在浏览器端调用，因为这涉及到很多安全性问题。

前端集成有两种方式。

在极简单的情况下，开发者没有后台服务，或者，后台服务不与前端交互（如仅有话单服务直接写库等），这时候，可以通过类似 XUI 的方式集成。如下图：

XSwitch 内置 HTTP 和 Websocket 服务器，客户可以直接从前端通过用户名密码登录系统，获取安全 Token 用于后续访问。

开发者有前端也有后端，前端浏览器想直接连 XSwitch 平台以使用一些现有的 API 和消息推送机制。

如图，客户浏览器可以直接连接 XSwitch。这种方式需要做一些 SSO（统一登录）之类的集成。两种方式都支持 HTTP/Websocket。当然这种方式不影响后端集成，可以看成一种混合方式。

为了安全，还是需要由开发者后台获取 Token，然后就可以以 HTTP、Websocket 方式登录 XSwitch 平台。

下面描述一个典型的用户登录流程。

为保证安全，浏览器连接 XSwitch 时使用使用安全 Token 登录。

使用前，开发者应该在 XSwitch 系统界面上通过admin用户创建开发者 Key。该 Key 用于开发者侧调用 XSwitch 的相关接口。

1. 用户在浏览器中填入“工号”、“密码”、“分机号”；
2. 浏览器请求后端服务鉴权，验证工号和密码，验证成功后浏览器成功登录后端服务；
3. 浏览器向后端服务发送“分机号”，后端服务则使用“开发者 Key”以及分机号向请求 XSwitch 服务，XSwitch 会返回一个“Token”，后端服务可以将该 Token 返回前端浏览器。
4. 浏览器使用“Token”可以连接 XSwitch 侧的 WebSocket。
5. 浏览器也可以使用该 Token 调用 XSwitch 提供的 REST 接口。可以通过X-XTRA-AUTH-ID: Token头域或在 Cookie 中传送，具体格式请参考相关 API 文档。

• 开发者应该缓存 Token，方便在页面刷新时使用
• 目前 Token 没有有效的 Expire 机制，因此，如果 Token 过期，应该重新使用上述机制获取 Token
• 建议在每次用户登录时重新获取 Token
• 在使用 Websocket 时，浏览器中的页面应该是一个典型的“单页面”应用程序，即在切换页面时不要经常刷新页面。如果使用 HTTP 则无此限制

不管后端还是前端集成，用户的 SIP 话机和浏览器是两个东西，前者使用 SIP 协议与 XSwitch 通信（通话），而后者 HTTP/Websocket 等协议与后台交互，获取和感知话机的通话状态。浏览器收到相关的呼叫消息后，可以调用 Javascript 在浏览器上显示主叫号码，发起后台查询查询用户信息并在界面上展示等。

浏览器上的按钮或号码点击事件可以通过 API 发送到 XSwitch，XSwitch 可以发起外呼。常用的场景有：

• 外呼一个号码，接通后播放个语音提示，如话费预警和其它通知等。
• 先呼坐席对应的分机号，呼通后再呼客户的手机号，将坐席跟手机接通。这种方式为回呼模式（回呼分机号，坐席需要先应答）。
• 通过 API 控制坐席的话机，自动发起呼叫。这种方式需要 XSwitch 有座席话机的控制权限，设置较复杂。

如果用户开发的系统不是 B-S 架构的，而是 C-S 架构的，则整体架构不变，只是把浏览器（B）换成你的客户端程序（C）即可。依此类推，在开发移动 App 的场景下，也可以把 B 换成 A（你的 App）。同样由于安全原因，推荐 App 直接连接开发者自己的后台。当然，如果直连 XSwitch 的前台我们也是支持的，只是需要更精心地设计安全登录鉴权流程。

不同的集成方式需要不同的安全策略和接口，具体参见《XSwitch 认证鉴权接口》。