1、服务开通说明

根据工业和信息化部对电信用户实名制的要求,以及对增值电信业务服务提供商的管理要求,云信使号码保护业务仅提供该业务的技术服务,不提供线路接入服务。需要使用该业务的用户,首先需要以用户企业的名义向基础运营商申请电话线路,线路开通后再接入到云信使业务平台,云信使平台协助客户实现业务逻辑及提供运维服务,收取技术服务费,该业务产生的通讯费,由用户直接支付给基础运营商。目前本业务仅针对有明确应用场景的行业客户开放,了解更多细节,请咨询客服。

2、业务流程介绍

1、用户系统向云信使系统提交号码保护(集中付费)任务请求,并指定业务逻辑(如通话双方的呼叫顺序,可以是同时呼叫,或先呼叫FromPhone);
2、云信使系统通过验证后开始呼叫通话双方,或先呼叫FromPhone(取决于用户定义的业务逻辑)
3、一方接听,开始呼叫另一方(取决于业务逻辑,如果需要),等待另一方接听
4、另一方接听,通话开始,通话过程中用户系统可以对录音进行控制,可以强制拆线;
5、通话结束,云信使系统将本次通话的CDR推送到用户系统;

3、接口地址与交互方式

接口地址:https://api.yunxinshi.com:8081/Protect.do

交互方式:用户系统以HTTPS POST的方式向服务器(上述接口地址)发送XML数据包,服务器接收并通过验证后开始执行业务流程。服务器将在执行过程中的必要节点向用户系统以HTTP方式回调消息以告知流程进度和其他相关数据;

4.1、接口功能:创建号码保护会话 ( StartSession )


功能说明:
该功能用于发起一个号码保护(集中付费)任务。

发送的XML数据包:
<xml>
   <ActionType>StartSession</ActionType>
   <UserName></UserName>
   <Token></Token>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <Caller></Caller>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <CallPolicy></CallPolicy>
   <MaxTalkSecond></MaxTalkSecond>
   <Record></Record>
   <CustomData></CustomData>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
FromPhone必填
ToPhone必填
Caller可选
FromPhoneIVR可选
ToPhoneIVR可选
CallPolicy可选
MaxTalkSecond可选
Record可选
CustomData可选

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <SessionSN></SessionSN>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
SessionSN

4.2、接口功能:结束号码保护会话 ( CloseSession )


功能说明:
该功能用于将一通正在通话中的号码保护任务挂断。

发送的XML数据包:
<xml>
   <ActionType>CloseSession</ActionType>
   <UserName></UserName>
   <Token></Token>
   <SessionSN></SessionSN>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
SessionSN必填

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg

4.3、接口功能:查询正在通话中的号码保护会话 ( QuerySession )


功能说明:
该功能用于查询正在通话中的号码保护会话的详细信息。

发送的XML数据包:
<xml>
   <ActionType>QuerySession</ActionType>
   <UserName></UserName>
   <Token></Token>
   <SessionSN></SessionSN>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
SessionSN必填

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <Recording></Recording>
   <FromPhoneCallTime></FromPhoneCallTime>
   <FromPhoneConnectTime></FromPhoneConnectTime>
   <ToPhoneCallTime></ToPhoneCallTime>
   <ToPhoneConnectTime></ToPhoneConnectTime>
   <StartTalkTime></StartTalkTime>
   <SessionStatus></SessionStatus>
   <FromPhoneStatus></FromPhoneStatus>
   <ToPhoneStatus></ToPhoneStatus>
   <CustomData></CustomData>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
SessionSN
Caller
FromPhone
ToPhone
Recording
FromPhoneCallTime
FromPhoneConnectTime
ToPhoneCallTime
ToPhoneConnectTime
StartTalkTime
SessionStatus
FromPhoneStatus
ToPhoneStatus
CustomData

4.4、接口功能:号码保护会话开始录音 ( StartRecord )


功能说明:
该功能用于对已经在通话状态中,且未处于录音状态的会话开始录音。

发送的XML数据包:
<xml>
   <ActionType>StartRecord</ActionType>
   <UserName></UserName>
   <Token></Token>
   <SessionSN></SessionSN>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
SessionSN必填

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg

4.5、接口功能:号码保护会话结束录音 ( EndRecord )


功能说明:
该功能用于对已经在通话状态中,且处于录音状态的会话停止录音。

发送的XML数据包:
<xml>
   <ActionType>EndRecord</ActionType>
   <UserName></UserName>
   <Token></Token>
   <SessionSN></SessionSN>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
SessionSN必填

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg

4.6、接口功能:查询号码保护历史记录 ( QuerySessionHistory )


功能说明:
该功能用于查询一通已经结束的会话的历史记录详情。

发送的XML数据包:
<xml>
   <ActionType>QuerySessionHistory</ActionType>
   <UserName></UserName>
   <Token></Token>
   <SessionSN></SessionSN>
</xml>


发送的XML数据包参数说明:

参数必要性含义
ActionType必填
UserName必填
Token必填
SessionSN必填

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <CallPolicy></CallPolicy>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <Record></Record>
   <RecordFiles></RecordFiles>
   <MaxTalkSecond></MaxTalkSecond>
   <ReceiveEventURL></ReceiveEventURL>
   <SubmitTime></SubmitTime>
   <FromPhoneCallTime></FromPhoneCallTime>
   <FromPhoneConnectTime></FromPhoneConnectTime>
   <ToPhoneCallTime></ToPhoneCallTime>
   <ToPhoneConnectTime></ToPhoneConnectTime>
   <StartTalkTime></StartTalkTime>
   <EndTime></EndTime>
   <CustomData></CustomData>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
SessionSN
Caller
CallPolicy
FromPhone
ToPhone
FromPhoneIVR
ToPhoneIVR
Record
RecordFiles
MaxTalkSecond
ReceiveEventURL
SubmitTime
FromPhoneCallTime
FromPhoneConnectTime
ToPhoneCallTime
ToPhoneConnectTime
StartTalkTime
EndTime
CustomData

5.1、回调消息:回调消息的推送地址和接收响应


回调消息推送地址的配置:
如果用户在管理平台的“业务管理”-“回调消息地址配置”中,配置了“号码保护(集中付费)”的回调消息地址,则当有这类消息触发时,云信使系统会将消息的详情推送到用户所配置的地址。该地址的配置如下图所示:

用户亦可在每次创建号码保护任务时动态变更回调消息的接收地址,如需实现该动态变更功能,请咨询技术客服。

用户系统接收后的响应:
用户系统成功接收消息后,返回字符串0。云信使系统如果未收到字符串0,则认为推送失败,会再次推送该消息(最多三次)。

5.2、回调消息:开始呼叫FromPhone(StartDialFromPhone)


消息说明:
当云信使系统开始呼叫任务设置的FromPhone时,触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>StartDialFromPhone</Event>
   <SessionSN></SessionSN>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

5.3、回调消息:开始呼叫ToPhone(StartDialToPhone)


消息说明:
当云信使系统开始呼叫任务设置的ToPhone时,触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>StartDialToPhone</Event>
   <SessionSN></SessionSN>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

5.4、回调消息:FromPhone接通(FromPhoneConnected)


消息说明:
当任务设置中的FromPhone接通时,触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>FromPhoneConnected</Event>
   <SessionSN></SessionSN>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

5.5、回调消息:ToPhone接通(ToPhoneConnected)


消息说明:
当任务设置中的ToPhone接通时,触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>ToPhoneConnected</Event>
   <SessionSN></SessionSN>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

5.6、回调消息:通话结束(HangUP)


消息说明:
当云信使系统呼叫FromPhone或ToPhone中任意一方失败时,或正在通话中任意一方挂断电话时,触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>HangUP</Event>
   <SessionSN></SessionSN>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

5.7、回调消息:推送本次呼叫日志(ReportCDR)


消息说明:
当会话结束时(不管是否双方已经通话),触发该事件。

接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Portect</Business>
   <Event>ReportCDR</Event>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <RecordFiles></RecordFiles>
   <SubmitTime></SubmitTime>
   <FromPhoneCallTime></FromPhoneCallTime>
   <FromPhoneConnectTime></FromPhoneConnectTime>
   <ToPhoneCallTime></ToPhoneCallTime>
   <ToPhoneConnectTime></ToPhoneConnectTime>
   <StartTalkTime></StartTalkTime>
   <EndTime></EndTime>
   <CustomData></CustomData>
   <Time></Time>
</xml>


接收的XML数据包参数说明:

参数含义
PushSN
UserName
Business
Event
SessionSN
Caller
FromPhone
ToPhone
RecordFiles
SubmitTime
FromPhoneCallTime
FromPhoneConnectTime
ToPhoneCallTime
ToPhoneConnectTime
StartTalkTime
EndTime
CustomData
Time
用户系统响应:
用户系统接收到该消息后,需要返回字符串0,云信使系统如果未接收到正确的返回,将在三秒内重发该消息(最多三次)。

6、使用在线调试工具快速测试

用户可以登录帮客云信使业务管理系统(https://www.yunxinshi.com/user/),通过“接口调试工具”--“号码保护(集中付费)”模块,快速测试与调试本功能。调试工具如下图所示: