API 参考

本文介绍小樱桃 XSwitch PSTN 相关的 RESTful API 和回调。

鉴权 API

XSwitch Cloud 支持通过 API 方式访问，使用 Session/Token 的鉴权方式。业务侧调用该 API 后，系统返回一个 JWT 格式的 Token。拿到 Token 后，即可携带 Token 访问有权限认证的 API。

请求 URL

Shell

POST https://cloud.xswitch.cn/api/cloud/token

请求参数

如果是第一次获取 Token，传入以下 Body 参数：

参数	必选	类型	描述
login	是	String	XSwitch 用户名
password	是	String	XSwitch 密码
domain	是	String	用户域
jwt	是	String	true 代表返回 JWT Token

示例如下：

Shell

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",
    "jwt": true
  }'

响应参数

如果成功，返回一个 JSON Object，包含以下字段：

• code：Int，响应状态码。
• token：String，可用作 Token (Header 中的 X-XTRA-AUTH-ID 字段)。
• expires：Int，Unix 时间戳，过期时间。
• refresh_token: Refresh Token，用于生成新的 token。

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

产生 JWT Token 示例：

JSON

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

当 Token 过期后，可以使用上面的 refresh_token 来生成新的 Token，示例如下：

Shell

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

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

外呼 API

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

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

请求 URL

Shell

POST https://cloud.xswitch.cn/api/cloud/callPSTN

请求参数

在请求 Body 中传入以下参数：

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

示例如下：

Shell

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 Object，包含以下字段：

• code：响应码，成功返回 200。
• message：信息描述，成功为 success。
• data：SIP 通话的唯一标识符，可用于挂机 API的 uuid 参数。

JSON

{
    "code": 200,
    "message": "success",
    "data":	"0bee39f2-...@JaJoJk..."
}

挂断 API

根据通话 UUID 挂断当前通话。

请求 URL

Shell

DELETE https://cloud.xswitch.cn/api/cloud/calls/{channel_uuid@hash_str}

请求参数

传入以下参数；

• Header 参数 channel_uuid@hash_str：标识本次通话的唯一标识符，可以使用呼出 API 返回的 uuid 值。
• Body 参数 hangup_cause：可选，默认为 NORMAL_CLEARING。可用的值可参考常用挂机原因说明。

示例如下：

Shell

curl -XDELETE https://cloud.xswitch.cn/api/cloud/calls/0bee39f2-...@JaJoJk... \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ey...' \
  -d '{
    "hangup_cause": "NORMAL_CLEARING"
  }'

呼入回调

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

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

鉴权

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

Shell

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 字符串鉴权。详见请求参数。

请求参数

包含以下参数：

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

响应参数

你需要在响应中以 JSON 形式返回以下信息：

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

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

Shell

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