XSwitch集成指南

XSwitch.cn

2022年5月17日

法律声明

若接收烟台小樱桃网络科技有限公司（以下称为“小樱桃”）的此份文档，即表示您已同意以下条款。若不同意以下条款，请立即停止使用本文档。

本文档版权所有烟台小樱桃网络科技有限公司。保留任何未在本文档中明示授予的权利。文档中涉及小樱桃的专有信息。未经小樱桃事先书面许可，任何单位和个人不得复制、传递、分发、使用和泄漏该文档以及该文档包含的任何图片、表格、数据及其他信息。本网页版文档仅在xswitch.cn上发布。

本产品符合有关环境保护和人身安全方面的设计要求，产品的存放、使用和弃置应遵照产品手册、相关合同或相关国法律、法规的要求进行。

本文档按“现状”和“仅此状态”提供。本文档中的信息随着小樱桃的产品和技术的进步将不断更新，小樱桃不再通知此类信息的更新。

烟台小樱桃网络科技有限公司

地址：烟台市高新区蓝海路1号
邮编：264000
电话：0535-6753997

1 集成指南

xswitch是基于FreeSWITCH开发的软交换系统，XUI是一套Web界面。统称XSwitch。

XSwitch提供开发接口便于第三方集成。XSwitch提供HTTP REST、Websocket和XCC接口。

2 集成架构

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

2.1 后端集成

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

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

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

后端集成包括：

• XSwitch REST API接口（联系我们）
• XSwitch XCC API接口
• XCC API Examples

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

2.2 前端集成

前端集成有两种方式。

2.2.1 纯前端集成

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

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

2.2.2 有后端的前端集成

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

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

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

2.2.3 用户登录步骤

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

为保证安全，浏览器连接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文档。

2.2.4 注意事项

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

3 认证

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

4 其它

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