1、服务开通说明

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

2、业务流程介绍

1、用户系统创建号码保护任务,等待通话双方中的任意一方主动呼入;
2、通话双方的任意一方呼入时,云信使系统向用户系统推送消息,告知会话起始;
3、根据任务的设置,云信使系统开始呼叫被叫电话(另一方);
4、被叫接通,双方通话开始;
5、任意一方挂断,通话结束,云信使系统向用户系统推送通话日志等消息;

3、接口地址与交互方式

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

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

4.1、接口功能:创建号码保护任务 ( CreateTask )


功能说明:
该功能用于创建一个号码保(分摊付费)任务,创建后,所指定的号码可以使用隐藏的号码(在返回值中列出)来呼叫双方。

发送的XML数据包:
<xml>
   <ActionType>CreateTask</ActionType>
   <UserName></UserName>
   <Token></Token>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <MaxTalkSecond></MaxTalkSecond>
   <ExpiredSecond></ExpiredSecond>
   <Record></Record>
   <EnableInBound></EnableInBound>
   <CustomData></CustomData>
</xml>


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

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

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


返回值参数说明:

参数含义
errorcode
errmsg
TaskSN
HidePhoneNumber

4.2、接口功能:更新号码保护任务的配置 ( UpdateTask )


功能说明:
该功能用于更改已经创建的任务的某些配置。

发送的XML数据包:
<xml>
   <ActionType>UpdateTask</ActionType>
   <UserName></UserName>
   <Token></Token>
   <TaskSN></TaskSN>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <MaxTalkSecond></MaxTalkSecond>
   <AddExpiredSecond></AddExpiredSecond>
   <Record></Record>
   <EnableInBound></EnableInBound>
   <CustomData></CustomData>
</xml>


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

参数必要性含义
ActionType必填
UserName必填
Token必填
TaskSN必填
FromPhoneIVR可选
ToPhoneIVR可选
MaxTalkSecond可选
AddExpiredSecond可选
Record可选
EnableInBound可选
CustomData可选

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


返回值参数说明:

参数含义
errorcode
errmsg

4.3、接口功能:删除号码保护任务 ( DeleteTask )


功能说明:
该功能用于删除一个处于有效状态的号码保护任务,删除即时生效,但不影响该任务下正在进行中的会话。

发送的XML数据包:
<xml>
   <ActionType>DeleteTask</ActionType>
   <UserName></UserName>
   <Token></Token>
   <TaskSN></TaskSN>
</xml>


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

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

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


返回值参数说明:

参数含义
errorcode
errmsg

4.4、接口功能:查询一个处于有效状态的号码保护任务 ( QueryTask )


功能说明:
该功能用于查询一个处于有效状态的号码保护任务。需要查询已经处于失效状态的号码保护任务,请参照第3.6节“查询一个号码保护任务记录及其历史会话的汇总 ( QueryTaskHistory )”。

发送的XML数据包:
<xml>
   <ActionType>QueryTask</ActionType>
   <UserName></UserName>
   <Token></Token>
   <TaskSN></TaskSN>
</xml>


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

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

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <TaskSN></TaskSN>
   <HidePhoneNumber></HidePhoneNumber>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <EnableInBound></EnableInBound>
   <Record></Record>
   <MaxTalkSecond></MaxTalkSecond>
   <ExpiredTime></ExpiredTime>
   <ReceiveEventURL></ReceiveEventURL>
   <CustomData></CustomData>
   <AddTime></AddTime>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
TaskSN
HidePhoneNumber
FromPhone
ToPhone
FromPhoneIVR
ToPhoneIVR
EnableInBound
Record
MaxTalkSecond
ExpiredTime
ReceiveEventURL
CustomData
AddTime

4.5、接口功能:查询所有处于有效状态的号码保护任务 ( QueryAllTask )


功能说明:
该功能用于查询本账号下当前所有有效的号码保护任务的详情。

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


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

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

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <TaskCount>(x)</TaskCount>
   <Task(x)>
     <TaskSN></TaskSN>
     <HidePhoneNumber></HidePhoneNumber>
     <FromPhone></FromPhone>
     <ToPhone></ToPhone>
     <FromPhoneIVR></FromPhoneIVR>
     <ToPhoneIVR></ToPhoneIVR>
     <EnableInBound></EnableInBound>
     <Record></Record>
     <MaxTalkSecond></MaxTalkSecond>
     <ExpiredTime></ExpiredTime>
     <ReceiveEventURL></ReceiveEventURL>
     <CustomData></CustomData>
     <AddTime></AddTime>
   </Task(x)>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
TaskCount
Task(x)
Task(x)/TaskSN
Task(x)/HidePhoneNumber
Task(x)/FromPhone
Task(x)/ToPhone
Task(x)/FromPhoneIVR
Task(x)/ToPhoneIVR
Task(x)/EnableInBound
Task(x)/Record
Task(x)/MaxTalkSecond
Task(x)/ExpiredTime
Task(x)/ReceiveEventURL
Task(x)/CustomData
Task(x)/AddTime

4.6、接口功能:查询一个号码保护任务记录及其历史会话的汇总 ( QueryTaskHistory )


功能说明:
该功能用于查询一个号码保护任务(已经过期或未过期均支持)的详情,及其已经发生的所有会话记录的详情。

发送的XML数据包:
<xml>
   <ActionType>QueryTaskHistory</ActionType>
   <UserName></UserName>
   <Token></Token>
   <TaskSN></TaskSN>
</xml>


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

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

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <TaskStatus></TaskStatus>
   <TaskSN></TaskSN>
   <HidePhoneNumber></HidePhoneNumber>
   <FromPhone></FromPhone>
   <ToPhone></ToPhone>
   <FromPhoneIVR></FromPhoneIVR>
   <ToPhoneIVR></ToPhoneIVR>
   <EnableInBound></EnableInBound>
   <Record></Record>
   <MaxTalkSecond></MaxTalkSecond>
   <ExpiredTime></ExpiredTime>
   <ReceiveEventURL></ReceiveEventURL>
   <CustomData></CustomData>
   <AddTime></AddTime>
   <SessionCount>(x)</SessionCount>
   <Session(x)>
     <SessionSN></SessionSN>
     <SessionType></SessionType>
     <MaxTalkSecond></MaxTalkSecond>
     <Record></Record>
     <RecordFiles></RecordFiles>
     <ReceiveEventURL></ReceiveEventURL>
     <Caller></Caller>
     <CallerIVR></CallerIVR>
     <CallerConnectTime></CallerConnectTime>
     <Callee></Callee>
     <CalleeIVR></CalleeIVR>
     <CalleeConnectTime></CalleeConnectTime>
     <EndTime></EndTime>
     <CustomData></CustomData>
   </Session(x)>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
TaskStatus
TaskSN
HidePhoneNumber
FromPhone
ToPhone
FromPhoneIVR
ToPhoneIVR
EnableInBound
Record
MaxTalkSecond
ExpiredTime
ReceiveEventURL
CustomData
AddTime
SessionCount
Session(x)
Session(x)/SessionSN
Session(x)/SessionType
Session(x)/MaxTalkSecond
Session(x)/Record
Session(x)/RecordFiles
Session(x)/ReceiveEventURL
Session(x)/Caller
Session(x)/CallerIVR
Session(x)/CallerConnectTime
Session(x)/Callee
Session(x)/CalleeIVR
Session(x)/CalleeConnectTime
Session(x)/EndTime
Session(x)/CustomData

4.7、接口功能:查询一通正在进行的号码保护会话 ( 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>
   <TaskSN></TaskSN>
   <SessionType></SessionType>
   <HidePhoneNumber></HidePhoneNumber>
   <Caller></Caller>
   <Callee></Callee>
   <CallerIVR></CallerIVR>
   <CalleeIVR></CalleeIVR>
   <MaxTalkSecond></MaxTalkSecond>
   <Record></Record>
   <Recording></Recording>
   <CallerConnectTime></CallerConnectTime>
   <CalleeConnectTime></CalleeConnectTime>
   <Status></Status>
   <CustomData></CustomData>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
SessionSN
TaskSN
SessionType
HidePhoneNumber
Caller
Callee
CallerIVR
CalleeIVR
MaxTalkSecond
Record
Recording
CallerConnectTime
CalleeConnectTime
Status
CustomData

4.8、接口功能:查询一通已经结束的号码保护会话的历史记录 ( QuerySessionHistory )


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

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


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

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

返回值:
<xml>
   <errcode></errcode>
   <errmsg></errmsg>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <SessionType></SessionType>
   <HidePhoneNumber></HidePhoneNumber>
   <MaxTalkSecond></MaxTalkSecond>
   <Record></Record>
   <RecordFiles></RecordFiles>
   <ReceiveEventURL></ReceiveEventURL>
   <Caller></Caller>
   <CallerIVR></CallerIVR>
   <CallerConnectTime></CallerConnectTime>
   <Callee></Callee>
   <CalleeIVR></CalleeIVR>
   <CalleeConnectTime></CalleeConnectTime>
   <EndTime></EndTime>
   <CustomData></CustomData>
</xml>


返回值参数说明:

参数含义
errorcode
errmsg
TaskSN
SessionSN
SessionType
HidePhoneNumber
MaxTalkSecond
Record
RecordFiles
ReceiveEventURL
Caller
CallerIVR
CallerConnectTime
Callee
CalleeIVR
CalleeConnectTime
EndTime
CustomData

4.9、接口功能:挂断号码保护会话 ( HangUP )


功能说明:
该功能用于强制挂断一通正在进行中的号码保护会话。

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


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

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

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


返回值参数说明:

参数含义
errorcode
errmsg

4.10、接口功能:号码保护会话开始录音 ( 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.11、号码保护会话结束录音 ( 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.12、接口功能:更新一通正在进行的会话的CustomData内容 ( UpdateCustomData )


功能说明:
该功能用于更新一通正在进行的会话的CustomData内容,在会话创建时,系统默认使用任务的CustomData的值,但用户可以在会话过程中使用本方法来更改会话的的CustomData标签内容。

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


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

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

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


返回值参数说明:

参数含义
errorcode
errmsg

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


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

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

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

5.2、回调消息:正向会话起始(OutBoundStart)


消息说明:
当号码保护任务中的FromPhone拨打隐藏号码来呼叫ToPhone时,触发该事件。

用户系统接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Guard</Business>
   <Event>OutBoundStart</Event>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <Callee></Callee>
   <CustomData></CustomData>
   <Time></Time>
</xml>


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

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

5.3、回调消息:反向会话起始(InBoundStart)


消息说明:
当号码保护任务中的ToPhone拨打隐藏号码来呼叫FromPhone时,触发该事件。

用户系统接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Guard</Business>
   <Event>InBoundStart</Event>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <Callee></Callee>
   <CustomData></CustomData>
   <Time></Time>
</xml>


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

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

5.4、回调消息:被叫接通,通话开始(Connected)


消息说明:
当被叫(可以是FromPhone,也可以是ToPhone)接听电话时,触发该事件,表明双方已经开始通话。

用户系统接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Guard</Business>
   <Event>Connected</Event>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <Callee></Callee>
   <CustomData></CustomData>
   <Time></Time>
</xml>


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

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

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


消息说明:
当通话双方当的任何一方挂断通话时,触发该事件,表明本次通话结束。当被叫未接听电话,主叫挂断时,该事件也会触发。

用户系统接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Guard</Business>
   <Event>HangUP</Event>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <Caller></Caller>
   <Callee></Callee>
   <CustomData></CustomData>
   <Time></Time>
</xml>


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

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

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


消息说明:
该事件与上述HangUP事件一同触发,向用户系统推送本次会话的详情。

用户系统接收的XML数据包:
<xml>
   <PushSN></PushSN>
   <UserName></UserName>
   <Business>Guard</Business>
   <Event>ReportCDR</Event>
   <TaskSN></TaskSN>
   <SessionSN></SessionSN>
   <SessionType>OutBound</SessionType>
   <RecordFiles></RecordFiles>
   <Caller></Caller>
   <CallerIVR></CallerIVR>
   <CallerConnectTime></CallerConnectTime>
   <Callee></Callee>
   <CalleeIVR></CalleeIVR>
   <CalleeConnectTime></CalleeConnectTime>
   <EndTime></EndTime>
   <CustomData></CustomData>
   <Time></Time>
</xml>


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

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

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

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