XSwitch 与声网对接

该接口实现RTC 与 SIP 互转，PSTN 对接落地。支持声网转 SIP、SIP 转声网。

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

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

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

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

声网 App 客户端呼叫 SIP。

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

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

• https://xswitch.cn/agora/basicVoiceCall/index.html
• https://xswitch.cn/agora/

• 手机呼叫一个 PSTN 号码或其他设备 SIP 呼叫进入 XSwitch。
• XSwitch 根据号码找到对应的路由送到路由中指定的URL服务（业务侧服务器提供回调地址）。
• 业务侧服务器返回声网 token、channel、uid 等信息。
• XSwitch 将声网模块加入对应的 channel。
• 业务服务器通知 App 加入相关的 channel。

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

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

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

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

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

• 请求 URL： /api/sessions
• 请求方式： POST
• 消息头：

• Body 信息：

• 返回值：

正常返回一个 Object。

如果出错，返回 HTTP 状态码如403等，详见HTTP 状态码参考及JSON 返回格式参考。

• 其它说明：

首先，用用户名和密码获取一个 Token，参数的提交方式有两种，一种是基于 URL 字符串（www-form-urlencoded），如：

curl -XPOST -d 'login=1007&password=$VeryGoodPassw0rd' 192.168.1.100:8081/api/sessions

也可以提交一个 JSON 请求，如：

curl -XPOST -d '{"login": "1007", "password": "$VeryGoodPassw0rd"}' \
-H "Content-Type: application/json" \
192.168.1.100:8081/api/sessions

返回：

{
  "system_roles": {
    "senior_roles_str": "()",
    "roles_str": "()"
  },
  "extn": "1001",
  "code": 200,
  "currentAuthority": "admin",
  "expires": 1652290471,
  "user_id": 3,
  "token": "cde1f2e1-4930-41c1-a883-0bca35de7ea6"
}

后续所有的请求（包括注销）都需要使用该token。例如

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
192.168.1.100:8081/api/agora/callPSTN

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

• 请求 URL: /api/agora/callPSTN
• 请求方式: POST
• 消息头: Content-Type: application/json
• Body 信息:

请求示例：

curl --request POST \
  --url https://vip.xswitch.cn/api/agora/callPSTN \
  --header 'X-XTRA-AUTH-ID: 01942ada-6d5d-708xxxxxxxx' \
  --header 'content-type: application/json' \
  --data '{
	"destNumber": "15666xxxxx",
	"token": "f53a9b52579b48dbbxxxxx",
	"cidName": "test",
	"cidNumber": "test",
	"channel": "3000",
	"domain": "vip.xswitch.cn"
}'

成功返回：data 中@前的数值为通话通道 UUID

{
  "code": 200,
  "message": "success",
  "data": "01959245-455d-7169-bf20-83478cdf7ecf@L43ODbLUMNB"
}

返回 JSON 说明：

• code：代码，成功返回200。
• message：信息描述，成功为success。
• data：SIP 通话 UUID@hash_str，可用于挂机接口的uuid参数。

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

SIP 呼入后根据路由设置，XSwitch 向业务侧发起回调，发送 POST 请求，数据使用 JSON 格式。所有字符串均使用 UTF-8 编码（如下所示例子）。

请求参数：

• uuid：当前通话唯一 ID
• cidName：字符串，主叫名称
• cidNumber：字符串，主叫号码
• destNumber：字符串，被叫号码
• remoteAddr：远端 IP 地址

返回 JSON：

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

希望业务侧URL返回参数如下（后续可根据需求修改）：

返回 JSON：

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

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

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

• 请求 URL: /api/agora/dtmf
• 请求方式: POST
• 消息头: Content-Type: application/json
• Body 信息:

请求示例：

curl --request POST \
  --url https://vip.xswitch.cn/api/agora/dtmf \
  --header 'X-XTRA-AUTH-ID: 01942ada-6d5d-708xxxxxxxx' \
  --header 'content-type: application/json' \
  --data '{
	"channel_uuid": "01959245-455d-7169-bf20-83478cdf7ecf",
	"data": "1"
}'

成功返回：data 中@前的数值为通话通道 UUID

{
	"code": 200,
	"msg": "OK"
}

根据通道 UUID 挂断当前通话，url 中的：channel_uuid@hash_str来自 callPSTN 接口的返回值`。

• 请求 URL: /api/agora/calls/:channel_uuid

• 请求方式: POST

• 消息头: Content-Type: application/json

• Body 信息:

• hangup_cause：可选，默认为NORMAL_CLEARING

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

示例

curl -XDELETE http://localhost:8081/api/agora/calls/0bee39f2-..... \
-H 'Content-Type: application/json' \
-H 'X-XTRA-AUTH-ID: xxxxxy...' \
-d '{
  "hangup_cause": "NORMAL_CLEARING"
}'