使用说明
小樱桃 XSwitch PSTN 目前支持如下功能和场景：
- 一对一通话：声网频道内的用户可以呼叫 SIP 终端或 PSTN 号码，SIP 设备或 PSTN 号码也可以呼入声网频道。
- 多人通话和会议：SIP 设备或 PSTN 号码可以呼入声网频道。
优势介绍
小樱桃 XSwitch PSTN 具有以下优势：
- 调用两个 RESTful API 即可实现 SIP/PSTN 呼入和呼出。
- 支持自动选择呼出号码（线路）。
- 支持指定呼出号码（线路）。
技术原理
小樱桃 XSwitch PSTN 是对 XSwitch 云平台通信能力的封装。集成声网音视频 SDK 后，通过小樱桃 XSwitch PSTN 提供的 RESTful API，你可以实现声网 SDK 客户端与 SIP 终端或 PSTN 电话号码的一对一通话和多人通话。
XSwitch 云平台简介
XSwitch 云平台是一个多租户的通信平台，每个租户对应一个“域”（域名），如小樱桃对应：cherry.xswitch.cn。
页面访问及 API 调用地址统一为 https://cloud.xswitch.cn/api/cloud，访问时或调用相应的 API 时通过传入的用户名、密码、域名进行分离。
租户可以直接使用主域名进行测试和使用。如果一个租户内有多个项目需要隔离（不同的号码段、号码池及话单），则可以在租户内建立下级租户。由于安全及审核的需要，目前下级租户的开通需要联系客服手工创建。后期将可以开通 Web 控制台自助管理。
系统架构
系统总体架构包含以下部分：
- 你的 App 客户端：需集成声网 RTC SDK。
- 你的业务侧服务端：与 XSwitch Cloud 交互控制相关呼叫逻辑。
- XSwitch Cloud：包含声网模块和 SIP 模块。
- 运营商、SIP 话机或者其它 SIP 服务。
快速体验
声网频道内呼叫 PSTN
-
联系声网获取专属的 XSwitch 账户、密码和域名。
-
获取用于 XSwitch 鉴权的 Token：在命令行工具中输入以下命令，并填入你的 XSwitch 账户名、密码和域名信息。
Shellcurl -X POST https://cloud.xswitch.cn/api/cloud/token \
-H 'Content-Type: application/json' \
-d '{
"login": "XXXXX",
"password": "XXXXXXX",
"domain": "XXX.xswitch.cn",
"jwt":true
}'请求发送成功后，你可以从响应包体中获取 XSwitch 的鉴权 Token。
-
加入声网频道：访问用于测试的声网 Web 客户端， 填写你在声网控制台获取的 App ID、RTC 临时 Token、频道名，然后点击 Join 加入声网频道。获取方式详见开通服务。
-
呼叫 PSTN 号码。在命令行工具中输入以下命令，并填写以下信息：
Authorization：你在步骤 2 获取的 XSwitch 鉴权 Token。destNumber：要呼叫的 PSTN 手机号码。token：在声网控制台获取的临时 Token。必须与你在步骤 3 中填入的一致。channel：声网频道名。必须与你在步骤 3 中填入的一致。domain：你申请的 XSwitch 域名。
Shellcurl -X POST https://cloud.xswitch.cn/api/cloud/callPSTN \
-H 'Authorization: Bearer xxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"destNumber": "XXXXXXXXXXX",
"token": "XXXXXXXXXXXXXXXX",
"channel": "XXXXX",
"domain": "XXX.xswitch.cn"
}' -
发送请求后，如果鉴权成功，你的 PSTN 手机号码将会响铃，接通即可加入声网频道。
PSTN 呼叫声网频道
- 联系声网获取专属的 XSwitch 账户、密码和域名。
- 登录 XSwitch 后台，配置用于接收呼入回调的服务器地址。声网提供用于测试的服务器地址，你可以联系我们获取。
- 加入声网频道：访问用于测试的声网 Web 客户端， 填写你在声网控制台获取的 App ID、RTC 临时 Token、频道名，然后点击 Join 加入声网频道。获取方式详见开通服务。
- 登录 XSwitch 后台，获取用于测试的 DID 号码。
- PSTN 手机号码拨打测试 DID 号码（+ 010），即可加入声网频道。
集成和调用流程
1. 集成声网 SDK
XSwitch 服务需要和指定版本的声网 SDK 搭配使用。你需要参考对应平台的集成文档，集成 SDK 并实现基础的语音通话。
| 平台 | 声网 SDK | 集成文档 |
|---|---|---|
| Android、iOS、macOS、Web、Windows | RTC 音频 SDK v4.x | 点击查看 |
| Linux | RTC 服务端 SDK 4.0.1 | 点击查看 |
2. 开通 XSwitch 服务
联系声网开通 XSwitch 服务，并获取专属的 XSwitch 账户、密码和域名，用于后续调用 RESTful API。
3. 呼入与呼出
声网客户端呼叫 PSTN
声网 App 客户端呼叫 PSTN 的流程如下：
- App 客户端从业务侧服务端获取声网 Token、频道、用户 ID 等信息。
- App 客户端加入频道。
- App 客户端通知业务侧服务端呼叫手机。
- 业务侧服务端调用外呼 API，呼叫手机。
- XSwitch 收到外呼请求，将声网模块加入与 App 相同的频道，
- XSwitch 通过 SIP 模块呼叫运营商。
- 手机振铃接听，App 与手机通话。
PSTN 呼叫声网客户端
SIP 呼叫声网 App 的流程如下：
- 手机呼叫一个 PSTN 号码进入 XSwitch。
- XSwitch 根据号码找到相关的租户信息，发送呼入回调到租户提供的 API（业务侧服务器）。
- 业务侧服务器接收回调，向客户端 App 返回声网 Token、频道、用户 ID 等信息。
- XSwitch 将声网模块加入对应的频道。
- 业务侧服务器通知 App 加入对应的频道。
最后三步的顺序可根据自己的业务逻辑调整。
4. 挂机
在一对一通话中，当通话建立后，会生成一个唯一的通话 UUID，可以通过挂断 API 指定 UUID 对应的通话。
系统也支持自动挂机：当 XSwitch 侧的声网 Linux SDK 加入一个 channel 后，如果检测到另一个 uid 加入相同的 channel 并离开，当前 channel 中只剩下 Linux SDK 时，XSwitch 侧的 Linux SDK 会自动退出channel，SIP 侧挂机。
在实际使用时，App 侧也可以使用相同的逻辑，检测到 channel 中的 uid 数从 2 变成 1 时自动挂机。
参考信息
API 参考
RESTful API 和回调参数的详细说明参考 API 参考。
示例项目
查看小樱桃提供的示例项目。
隐私和安全
- 根据国家有关法律法规，XSwitch Cloud 平台需要留存通话记录 6 个月。
- 根据国家有关法律法规，所有登录系统和使用 API 的用户都必须实名。
- XSwitch 不会向第三方泄漏您的通话记录，也永远不会使用您的通话记录做大数据挖掘、分析等。
- XSwitch 平台不存储您的用户数据，所有用户数据都存储在您自己的服务器上。
- 为了能接通服务，XSwitch 需要声网侧产生的临时 Token、频道名、用户 ID 等数据，由于计费、故障追踪等需要，可能会存储 2-3 个月。这些数据都是由您的服务端生成的，最好不要包含敏感信息。平台不会对这些数据进行任何大数据挖掘和分析等。
测试号码
小樱桃提供了一批 10000 开头的测试号码用于开发测试，如：
10000183：回彩铃，不接听10000200：自动接听，放广告语10000201：自动接听，放广告语，约 1 分钟10000202：自动接听，放广告语，约 2 分钟10000486：不接听，放被叫忙
这些号码仅供 SIP 测试，不保证一直可用。详见更多测试号码。