XSwitch Cloud

小樱桃XSwitch声网SIP-PSTN网关

RTC与SIP互转，PSTN对接落地。支持声网转SIP、SIP转声网、SIP加入声网会议等，提供PSTN号码资源、用户也可以对接自己的PSTN中继。

功能

XSwitch Cloud目前支持如下功能和场景：

  • 声网转SIP（PSTN）：声网App客户端可以呼叫SIP终端或PSTN电话号码，实现一对一通话。
  • SIP（PSTN）转声网：SIP设备或PSTN电话可以呼入声网频道，跟App一对一通话。
  • SIP呼入声网会议：SIP设备或PSTN电话可以呼入声网频道，实现多对多会议。
  • 邀请SIP（PSTN）用户加入声网会议：通过API，可以
  • 多租户

XSwitch Cloud使用云计算技术和分布式技术构建，支持多租户、支持弹性伸缩。

XSwitch Cloud提供简单易用的API，可以快速开通和对接应用。

XSwitch Cloud提供优质PSTN号码资源和落地对接，可以快速打通电话。

优势

  • 两个REST API实现SIP呼入、呼出
  • 支持自动选择呼出号码（线路）
  • 支持指定呼出号码（线路）

使用指南

理解XSwitch云平台

XSwitch云平台是一个多租户的通信平台，每个租户对应一个“域”（域名），如小樱桃对应：cherry.xswitch.cn。

页面访问及API接口调用地址统一为https://cloud.xswitch.cn/api/cloud，访问时或调用相应的API时通过传入的用户名、密码、域名进行分离。

租户可以直接使用主域名进行测试和使用。如果一个租户内有多个项目需要隔离（不同的号码段、号码池及话单），则可以在租户内建立下级租户。由于安全及审核的需要，目前下级租户的开通需要联系客服手工创建。后期将可以开通Web控制台自助管理。

前期准备

重要：

  • 在声网网站上开通声网账号 https://www.shengwang.cn/ 。
  • 在声网控制台上添加一个项目，如“XSwitch Cloud Test”：
    • 简单起见，创建项目时，“鉴权机制”可以填调试模式，等调试通过后再关闭。
    • 如果使用安全模式，则可以在项目控制台上生成一个临时的Token。
    • 下面，需要使用声网Token的地方都兼容临时Token和项目App ID。

准备好后可以先到 https://xswitch.cn/agora/basicVoiceCall/index.html 测试，打开两个网页，输入相同的App ID、Token（可选）及Channel Name后，分别点击【Join】可以互相通话，点击【Leave】离开。

使用流程

  • 准备相关信息
    • 是否需要XSwitch提供PSTN号码，还是自带SIP中继
    • 如果需要XSwitch提供PSTN号码，需要提供以下信息
      • 落地城市
      • 呼入、呼出，还是双向
      • 号码数量
      • 每线并发数
      • 普通号码还是需要AXB号码
      • 业务类型、使用场景
      • 业务类型、相应的话术等
      • 公司名称，用于开通租户
      • 相应的域名，用于开通租户，域名以xswitch.cn结尾，如cherry.xswitch.cn是小樱桃的域名。
      • 呼叫服务器回调地址，如https://cherry.xswitch.cn/api/callback/agora-callback。
  • 从声网云市场购买XSwitch SIP-PSTN网关
  • XSwitch 开发者账号（线下获取）

由于PSTN号码安全管控需要，PSTN号码开通流程需要通过线下进行，视情况可能需要1～7个工作日。

系统架构

系统总体架构如下图所示：

系统集成逻辑如下图所示：

其中，业务侧的App集成声网SDK，App连接自己的后台服务器（上图中的“业务侧服务器”）。后台服务器与XSwitch交互控制相关呼叫逻辑。详细呼叫流程如下节所述。

呼叫流程

有SIP参与的基本呼叫流程如下。

声网呼SIP

声网App客户端呼叫SIP。

  • App从业务侧服务器后台获取声网token、channel、uid等信息，（在调试模式下，token的值也可以填App ID的值）。
  • App加入channel。
  • App通知服务器呼叫手机。
  • 服务器调用外呼API，呼叫手机。
  • XSwitch收到外呼请求，将声网模块加入与App相同的channel。
  • XSwitch通过SIP模块呼叫运营商。
  • 手机振铃接听。
  • App与手机通话。

注：声网App侧可能是任何的声网SDK客户端，如果没有现成的客户端，可以使用如下在线网页测试：

SIP呼叫声网App

  • 手机呼叫一个PSTN号码进入XSwitch。
  • XSwitch根据号码找到相关的租户信息，回调租户提供的API接口（业务侧服务器）。
  • 业务侧服务器返回声网token、channel、uid等信息。
  • XSwitch将声网模块加入对应的channel。
  • 业务服务器通知App加入相关的channel。

注：以上最后三步的顺序可根据自己的业务逻辑调整。

呼叫进展消息

Todo.

通话记录推送

Todo.

挂机流程

在一对一通话中，当通话建立后，会生成一个唯一的通话UUID，可以通过REST API的DELETE接口，挂断指定UUID对应的通话。

系统也支持“自动”挂机：

当XSwitch侧的声网Linux SDK加入一个channel后，如果检测到另一个uid加入相同的channel并离开，当前channel中只剩下Linux SDK时，XSwitch侧的Linux SDK会自动退出channel，SIP侧挂机。

在实际使用时，App侧也可以使用相同的逻辑，检测到channel中的uid数从2变成1时自动挂机。

API接口

下面是涉及到的API接口，示例主要以cURL形式描述，文末有相关的示例代码。

鉴权

业务侧调用XSwitch鉴权

XSwitch Cloud支持通过API方式访问。使用Session/Token的鉴权方式，业务侧通过认证API拿到Token后，即可携带Token访问有权限认证的接口。

业务侧通过“用户名”、“密码”、“域名”及“jwt”发起请求，系统返回一个JWT格式的Token。

请求参数说明

参数必选类型备注
login是string用户名
password是string密码
domain是string用户域
jwt是stringtrue，返回JWT Token

POST /api/cloud/token

示例

curl -X POST https://cloud.xswitch.cn/api/cloud/token \
-H 'Content-Type: application/json' \
-d '{
  "login": "cloud_xxx",
  "password": "xxx",
  "domain": "cherry.xswitch.cn",
}'

正常返回一个JSON Object。

  • code：结果代码
  • token：string，可用作Token (X-XTRA-AUTH-ID)
  • expires：int，UNIX时间戳，过期时间
  • refresh_token: refresh token 用于更新 token

如果出错，返回HTTP状态码如403（用户名/密码错）500（内部错误）等。

产生JWT Token示例：

{
	"code":	200,
	"expires":	1692576984,
	"refresh_token":	"ey...",
	"token":	"ey..."
}

当token过期后，可以使用上面的refresh_token来属性新的token 使用refresh_token来产生新的JWT Token示例：

curl -X POST https://cloud.xswitch.cn/api/cloud/token \
-H 'Content-Type: application/json' \
-d '{
  "refresh_token": "ey..."
}'

返回结果可以参考上面的示例。

XSwitch回调业务侧接口鉴权

XSwitch回调业务侧接口时，可以使用IP地址白名单鉴权。目前，XSwitch回调的IP地址如下，请加入防火墙白名单：

212.129.138.139
43.140.224.96
211.159.171.210
211.159.155.29
211.159.155.30
49.232.232.170

此外，XSwitch在回调时可以在JSON中携带一个事先约定的cookie字符串，服务侧也可以根据该cookie字符串鉴权。

外呼接口

通过接口呼叫PSTN，采用JSON格式。当发起外呼时，需客户侧提供domain、token、channel、destNumber必选参数。

发起外呼后，查询trunks表，根据domain确定remote_add（外呼时选的线路地址），从而实现呼叫指定被叫号码并加入到指定的agora通道

外呼参数如下：

  • domain：域，必选，必须与认证信息中的域相同。
  • token：必选，加密的Agora Token。
  • channel：必选，字符串。
  • uid：字符串，可选，如不存在或为空则自动选择（缺省为被叫号码）。
  • destNumber：必选，被叫号码，E.164格式，如+86186xxxxxxxx。其中10000200是小樱桃提供的虚拟测试号码，自动接听，参见测试号码。
  • cidName：可选，字符串，如不选系统自动分配。
  • cidNumber：可选，字符串，如不选系统自动分配。
  • uuid：可选，UUIDv4格式，呼出的SIP Channel的UUID，可用于跟业务侧的呼叫ID关联。

POST /api/cloud/callPSTN

curl -X POST https://cloud.xswitch.cn/api/cloud/callPSTN \
-H 'Authorization: Bearer eyJxxx.yyy.zzz' \
-H 'Content-Type: application/json' \
-d '{
	"destNumber": "10000200",
	"token": "9fd575ca8600xxxxxxxxxxxx",
	"channel": "xswitch-cloud",
	"domain": "cherry.xswitch.cn"
}'

返回JSON：

  • code：代码，成功返回200。
  • message：信息描述，成功为success。
  • data：SIP通话UUID，可用于挂机接口的uuid参数。
{
	"code":	200,
	"message":	"success",
	"data":	"0bee39f2-7a2b-4c07-9b3c-b25638aff871"
}

呼入接口

呼入接口由业务侧提供URL。即业务方根据如下接口约定提供所需Agora信息接口用于呼入。

SIP呼入后，XSwitch Cloud会根据主叫号码、域名等查找DID从而查找到该租户对应的URL, 并发送POST请求，数据使用JSON格式。所有字符串均使用UTF-8编码（如下所示例子）。

请求参数：

  • ver：协议版本号，目前固定为1.0
  • uuid：当前通话唯一ID
  • cidName：字符串，主叫名称
  • cidNumber：字符串，主叫号码
  • destNumber：字符串，被叫号码
  • domain：当前租户对应的域
  • remoteAddr：远端IP地址
  • cookie：可选字符串，由业务方提供，可用于鉴权

返回JSON：

  • token：必选，加密的Agora Token或不加密的App ID
  • channel：必选，字符串
  • uid：字符串，可选，如不存在或为空则自动选择（缺省设置为cidName主叫名称）
  • cidName：可选，字符串，覆盖主叫用户名称
  • cidNumber：可选，字符串，覆盖主叫用户号码

agora客户接口模拟测试（其中agora-call-in为客户侧自主提供的接口URL）：

curl -XPOST -H "Content-Type: application/json" -d '{"ver":"1.0","uuid":"fbb53115-f52d-625xxxxx","cidName":"test","cidNumber":"10010","destNumber":"777","domain":"cherry.xswitch.cn","remoteAddr": "192.168.1.7"}' http://localhost:8088/api/agora-call-in

挂断接口

根据通道UUID挂断当前通话，url中的：channel_uuid为通话的uuid，可以使用callPSTN接口返回的uuid值。

挂断接口参数如下：

  • hangup_cause：可选，默认为NORMAL_CLEARING

hangup_cause可用的值可参考：https://docs.xswitch.cn/xpedia/hangup-cause/ 。

DELETE /api/cloud/calls/:channel_uuid

示例

curl -XDELETE http://localhost:8088/api/cloud/calls/fbb53115-f52d-625xxxxx \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ey...' \
-d '{
  "hangup_cause": "NORMAL_CLEARING"
}'

隐私和安全

  • 根据国家有关法律法规，XSwitch Cloud平台需要留存通话记录6个月。
  • 根据国家有关法律法规，所有登录系统和使用API的用户都必须实名。
  • XSwitch不会向第三方泄漏您的通话记录，也永远不会使用您的通话记录做大数据挖掘、分析等。
  • XSwitch平台不存储您的用户数据，所有用户数据都存储在您自己的服务器上。
  • 为了能接通服务，XSwitch需要声网侧产生的临时token、channel、uid等数据，由于计费、故障追踪等需要，可能会存储2-3个月。这些数据都是由您的服务端生成的，最好不要包含敏感信息。平台不会对这些数据进行任何大数据挖掘和分析等。

测试号码

小樱桃提供了一批10000开头的测试号码用于开发测试，如：

  • 10000183：回彩铃，不接听
  • 10000200：自动接听，放广告语
  • 10000201：自动接听，放广告语，约1分钟
  • 10000202：自动接听，放广告语，约2分钟
  • 10000486：不接听，放被叫忙

这些号码仅供SIP测试，不保证一直可用。详见更多测试号码。

示例代码

参见：https://git.xswitch.cn/xswitch/cloud-examples 相关说明。

XSwitch Cloud