通知 API

LinkRTC 后台服务通过通知 API 将通知类型的消息数据 POST 到用户的应用服务程序。

digraph notify_api { a [label="api.linkrtc.com"] b [label="http://your.app.com/your/script.php"] a -> b [label="POST"] }

用户应用服务程序通过这些通知数据判断呼叫或者客户端的状态,以便对其进行控制。

接收通知消息的 URL 通过 用户控制台 设置。

注意

在通知 API 中, LinkRTC 作为 HTTP 客户端,用户应用服务程序作为 HTTP 服务器。

所以: 开发者的 Web 服务程序需要向 LinkRTC 提供访问地址!

通知消息的内容是 JSON 对象格式。

JSON 对象的最外层包括两个属性:
  • type: 消息类型字符串。
  • data: 消息参数,其数据类型随事件类型不同而各异。

例如:

{
    "type": "call.CallStateChanged",
    "data": {
        "call": {
            "id": "2341",
            "dir": "incoming",
            "from": "13283484795",
            "to": "400666255343",
            "...": "... ..."
        }
    }
}

本节文档使用面向对象语言类型定义的伪代码形式,描述通知消息 data 部分的数据结构。

呼叫状态变化

type:event.CallStateChanged
class sapi.event.CallStateChanged
call

状态发生变化的呼叫

返回类型:sapi.Call

举例:

ID2341 的入方向呼叫产生:

POST /your/script.php HTTP/1.1
Host: your.company.com
Content-Type: application/json; charset=utf-8
Content-Length: xxx
X-LinkRTC-Timestamp: 1453543759
X-LinkRTC-Signature: E6E157A9FA805921DA12A86A40CC2A15

{
    "type": "event.CallStateChanged",
    "data": {
        "call": {
            "id": "2341",
            "dir": "incoming",
            "current_state": "pending",
            "...": "... ..."
        }
    }
}

警告

当用户应用服务程序收到呼叫状态变化事件通知中, data 部分的 sapi.Call 对象的当前状态属性 sapi.Call.current_state 值为 待定 (pending) , 且呼叫方向属性 sapi.Call.dir 值为 出方向 (outgoing) 时, 用户应用服务程序需要在呼叫超时或者被放弃之前调用 POST /v0.1/sapi/call/(str:call_id)/allow 允许此次呼叫,方可使出方向呼叫继续进行。

同理,当 data 部分的 sapi.Call 对象的当前状态属性 sapi.Call.current_state 值为 待定 (pending) , 且呼叫方向属性 sapi.Call.dir 值为 入方向 (incoming) 时, 用户应用服务程序需要在呼叫超时或者被放弃之前调用 POST /v0.1/sapi/call/(str:call_id)/switch 允许此次呼叫,方可使入方向呼叫继续进行。

WebRTC 客户端连接状态变化

WebRTC 客户端连接建立或者连接断开

type:event.WebRtcClientConnectStateChanged
class sapi.event.WebRtcClientConnected
connected
  • true: 连接建立
  • false: 连接断开
返回类型:bool
client

连接状态发生变化的客户端

返回类型:sapi.WebRtcClient

举例:

IDsx3kerjsWebRTC 客户端建立连接:

POST /your/script.php HTTP/1.1
Host: your.company.com
Content-Type: application/json; charset=utf-8
Content-Length: xxx
X-LinkRTC-Timestamp: 1453543759
X-LinkRTC-Signature: E6E157A9FA805921DA12A86A40CC2A15

{
    "type": "event.WebRtcClientConnectStateChanged",
    "data": {
        "connected": true,
        "client": {
            "id": "sx3kerjs",
            "..": "....",
            "...": "... ..."
        }
    }
}