# 通话状态通知

# 简介

获取通话状态通知是菊风云平台提供的一项服务。通过该服务,您的服务器可以获得通话的实时状态通知,从而使您能够在通话业务的基础上增加额外的业务控制。

文档描述基于您已经完成以下工作:

基本架构

image

# 控制台配置通知服务器

为了获取通话状态通知,您需要在控制台设置接收通话状态通知的服务器地址、鉴权用户名和密码:

  1. 进入控制台 - 服务管理 - 应用管理
  2. 操作 一栏中点击 设置 image-20200925141010930图标
  3. 状态配置 中 点击 添加状态服务器 后的 添加image-20200925140937588 按钮

image-20200925141336897

其中:

  • HTTP 鉴权域用户名和用户密码,是用于访问您的服务器的用户名和密码

  • 服务器 URL 是您的服务器访问的 URL 信息

    • 如果您的服务器通过 HTTPS 访问,请对应选择 HTTPS
    • 如果您的服务器通过域名访问,这里需要填入对应域名
    • 如果您的服务器有特定的访问路径,请一并填入。例如 112.124.116.65:7123/call_status/

TIP

配置将在 15 分钟内生效。

# 重发机制

为保证状态通知的可靠性,菊风服务器按照以下规则重发通知请求:

  • 事件发生时发送第一次通知请求
  • 正确响应要求响应中的 tid 和请求中的 tid 保持一致,并且 ret 的值为 true
  • 没有收到正确响应的情况下,间隔 2 分钟重发一次,一共重发 5 次

# 消息格式

statusNotify 消息用于通知通话状态,由菊风服务器发起 RESTful 请求,由客户服务器响应。获取通话状态通知的操作如下:

# 请求

HTTP报文样例:

POST / HTTP/1.1
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 535
Content-Type: application/json
Domain: john.lu_juphoon.com
Host: 182.92.66.126:71234

{"tid":4174673023,
"oid":"OpenCallUser",
"cmd":"statusNotify.OpenCall.CallEx",
"in":{"callId":94532840325125,
    "status":"call released by ([username:t123@test.com]) "
    "params":{"CallId":"94532840325125",
                "CallAppId":"2",
                "CallDomainId":"100299",
                "CallMediaType":"voice",
                "CalleeAccountId":"[username:t123@test.com]",
                "CallerAccountId":"[username:t456@test.com]",
                "CallOriginateTime":"1442456670",
                "CallAnswerTime":"1442456676",
                "CallTalkingDuration":"47",
                "ReleaseCallBy":"[username:t123@test.com]",
                "ReleaseCallReason":"User Terminate"
                },
    },
"params":{}
}

HTTP报文头:

报文头域 是否必选 说明
POST
Authorization Basic
[Base64(菊风分配的域用户名:密码)]
此处假定客户指定的HTTP鉴权用户名为user,密码为password,"dXNlcjpwYXNzd29yZA=="为(“user:password”)字符串经过Base64编码后的结果
Content-Length HTTP Body的实际长度
Content-Type application/json
Domain 发起请求者的域名

配置参数:

值的格式/类型 说明
tid int 事务ID。一次状态通知交互过程。客户服务响应消息中应携带对应值
callId string 通话ID,一次通话的唯一标识
status string
  • "user(xxx) trying",表示正在尝试呼叫xxx用户,但尚未接通"user(xxx) joined",表示xxx用户已接听,被接入到呼叫中;
  • "user(xxx) left”,表示xxx用户从呼叫中断开;
  • "call released by (xxx)”,表示呼叫已被释放。xxx可能是用户,也可能是服务器
CallerAccountId string 主叫用户的帐号
CalleeAccountId string 被叫用户的帐号
CallMediaType string 媒体类型,语音为 voice,视频为 video
CallOriginateTime string 呼叫发起的 UNIX 时间戳,单位秒
CallAnswerTime string 呼叫接听的 UNIX 时间戳,单位秒。如果值为 0 表示未进入通话状态
CallTalkingDuration string 通话时长,单位为秒。若值为0表示未进入通话状态
ReleaseCallBy string 呼叫释放方信息:
  • 如果值为用户帐号则代表由该用户释放呼叫
  • 如果值为 OpenCallServer 则代表由客户侧服务器释放
  • 如果值为CallServer则代表由菊风侧服务器释放
ReleaseCallReason string 释放的原因:
  • "Not Exists:xxx",代表xxx用户的账户ID不合法。
  • "No Sessions:xxx", 代表xxx用户的帐号ID未正常登录(Login)。
  • "Inactive Call Clean", 代表主叫客户端未能在规定的时间内(120s)发起呼叫,原先分配的CallId被清理掉。
  • "User Terminate:xxxx", 代表主叫或被叫用户主动挂机而导致的呼叫释放,其中 xxxx 代表终端释放的原因值。
  • "OpenCallServer Terminate", 代表客户服务器调用releaseCall操作而导致的呼叫释放、
  • "Timeout", 代表被叫侧超时(60s内)未接听呼叫,而导致服务器释放掉呼叫。

# 响应

HTTP报文样例:

HTTP/1.1 202 Accepted
Cntent-Length: 29

{"tid":4174673023,"ret":true}

HTTP报文头:

报文头域 是否必选
202 Accepted
Authorization Basic
[Base64(菊风分配的域用户名:密码)]
Demain HTTP Body的实际长度
Content-Length application/json

配置参数:

值的格式/类型 说明
tid int 事务ID。您的HTTP服务器回复的响应中,该字段的值应与请求报文保持一致。
ret boolean true表示收到通知。