3、接口功能(主动调用)
3.5、删除短信签名 ( DeleteSignature )
3.6、查询短信签名的状态 ( QuerySignature )
3.7、查询账号下所有短信签名 ( QueryAllSignature )
4、回调消息(系统推送)
1、用户系统向云信使系统提交短信发送请求;
2、云信使系统处理请求,下发短信;
3、云信使系统收到运营商成功或者失败的发送状态报告后,将状态报告推送给用户系统;
4、云信使系统收到手机回复的短信时,将收到的消息主动推送给用户系统;
5、用户系统也可以主动查询所发送信息的状态报告,以及主动刷新查询手机回复的消息;
接口地址:https://api.yunxinshi.com:8081/SMS.do
交互方式:用户系统以HTTPS POST的方式向服务器(上述接口地址)发送XML数据包,服务器接收并通过验证后开始执行业务流程。服务器将在执行过程中的必要节点向用户系统以HTTP方式回调消息以告知流程进度和其他相关数据;
功能说明:
该接口用于发送短信。
发送的XML数据包:
<xml>
<ActionType>MT</ActionType>
<UserName></UserName>
<Token></Token>
<Phones></Phones>
<Content></Content>
<Signature></Signature>
<RequiredReport>true</RequiredReport>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值MT |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
Phones | 必填 | 发送短信的号码,多个号码用半角逗号隔开,群发时建议每次100个号码 |
Content | 必填 | 发送短信的内容,最多支持670个字(不区分中英文),少于70字(含短信签名)按1条计费,多于70字(含短信签名)的计费方法请咨询客服 |
Signature | 可选 | 本次发送所使用的签名,留空表示使用账户的默认签名。一个账号可以有多个不同的签名,签名可以通过AddSignature接口提交 |
RequiredReport | 可选 | true或false,是否使用回调消息方式接收状态报告,只有当用户配置过回调消息接收地址后,该设置才会生效 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<SN></SN>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
SN | 调用成功返回本次发送的序列号,用户系统可以保存该序列号以区分回调消息的归属和查询历史记录,调用失败时无此参数 |
功能说明:
该接口用于主动向云信使服务器查询是否有新的回复短信。如果用户启用了回调消息机制,则不需要使用本接口(启用回调消息机制,当云信使系统收到手机回复消息时,会主动将消息推送给用户)。
发送的XML数据包:
<xml>
<ActionType>MO</ActionType>
<UserName></UserName>
<Token></Token>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值MO |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<MoCount>(x)</MoCount>
<MO(x)>
<FromPhone></FromPhone>
<ToNumber></ToNumber>
<Signature></Signature>
<Content></Content>
<ReceiveTime></ReceiveTime>
</MO(x)>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
MoCount | 本次获取的回复短信的数量 |
MO(x) | 根据MoCount的数量,通过<MO(x)></MO(x)>的形式返回多个回复短信的详情 |
MO(x)/FromPhone | 回复短信的手机号码 |
MO(x)/ToNumber | 接收短信的特服号码 |
MO(x)/Signature | 短信归属的短信签名 |
MO(x)/Content | 接收短信的内容 |
MO(x)/ReceiveTime | 接收的时间 |
功能说明:
该接口用于让用户主动查询某个号码的发送详情和状态报告。
发送的XML数据包:
<xml>
<ActionType>QueryReport</ActionType>
<UserName></UserName>
<Token></Token>
<SN></SN>
<Phone></Phone>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值QueryReport |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
SN | 必填 | 所要查询的批次序列号,序列号在发送短信时已经作为返回值返回给用户系统 |
Phone | 必填 | 所要查询手机号码,该手机号码必须存在于上述SN序列号所指向的短信批次中,否则无法查询 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<SN></SN>
<Phone></Phone>
<Status></Status>
<SubmitTime></SubmitTime>
<SendTime></SendTime>
<ReportTime></ReportTime>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
SN | 该条短信所在的批次的序列号 |
Phone | 查询的手机号码 |
Status | 运营商的状态报告 ,根据该值可以判断接收状态 |
SubmitTime | 短信提交的时间 |
SendTime | 短信实际发送的时间 |
ReportTime | 接收到运营商状态报告的时间 |
功能说明:
该接口用于增加新的签名,签名必须有实际含义的内容,不能是中性的内容(如“客服”),一个账户可以存在绑定多个签名,提交新签名时,需要填写正确的使用单位/组织名称,并简要描写用途。提交后需要等待审核和备案(一般当天完成),用户可以通过“查询短信签名的状态”接口查询审核状态。
发送的XML数据包:
<xml>
<ActionType>AddSignature</ActionType>
<UserName></UserName>
<Token></Token>
<Signature></Signature>
<OrganizationName></OrganizationName>
<Description></Description>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值AddSignature |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
Signature | 必填 | 要新增的短信签名,短信签名会占用短信发送字数,一般在2~8个字之间,直接填写签名内容即可,系统会自动加上粗括号 |
OrganizationName | 必填 | 使用该签名的单位/组织名称,必须是真实有效的名称 |
Description | 可选 | 备注/说明信息 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<Information></Information>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
Information | 附加的提示消息,该消息可以忽略 |
功能说明:
该接口用于删除已有的短信签名,删除后不可恢复,如果需要重新使用已经删除的签名,需要重新提交审核。
发送的XML数据包:
<xml>
<ActionType>DeleteSignature</ActionType>
<UserName></UserName>
<Token></Token>
<Signature></Signature>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值DeleteSignature |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
Signature | 必填 | 要删除的短信签名 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
功能说明:
该接口用于让用户查询所提交的签名的审核状态、分配的短信号码等信息。
发送的XML数据包:
<xml>
<ActionType>QuerySignature</ActionType>
<UserName></UserName>
<Token></Token>
<Signature></Signature>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值QuerySignature |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
Signature | 必填 | 所要查询的短信签名 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<Signature></Signature>
<Status></Status>
<ServiceID></ServiceID>
<OrganizationName></OrganizationName>
<Description></Description>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
Signature | 所查询的短信签名 |
Status | 短信签名的审核状态,Ready表示可用 |
ServiceID | 与短信签名匹配的唯一特服务号 |
OrganizationName | 使用该短信签名的单位/组织名称 |
Description | 备注/说明信息 |
功能说明:
该接口用于获取本账号下所有的短信签名及详情。
发送的XML数据包:
<xml>
<ActionType>QueryAllSignature</ActionType>
<UserName></UserName>
<Token></Token>
</xml>
发送的XML数据包参数说明:
参数 | 必要性 | 含义 |
---|---|---|
ActionType | 必填 | 固定值QueryAllSignature |
UserName | 必填 | 账号名 |
Token | 必填 | 使用32位MD5对原始密码进行加密,并将加密结果转换为大写得出Token值 |
返回值:
<xml>
<errcode></errcode>
<errmsg></errmsg>
<DefaultSignature></DefaultSignature>
<DefaultSignatureServiceID></DefaultSignatureServiceID>
<SignatureCount>(x)</SignatureCount>
<Signature(x)>
<Signature></Signature>
<Status></Status>
<ServiceID></ServiceID>
<OrganizationName></OrganizationName>
<Description></Description>
</Signature(x)>
</xml>
返回值参数说明:
参数 | 含义 |
---|---|
errorcode | 调用成功时返回“0”,调用失败时返回大于0的失败代码并在errmsg中描述具体的失败原因 |
errmsg | 调用成功时返回“成功”,调用失败时返回具体的失败原因的中文描述 |
DefaultSignature | 本账号默认的签名,当发送短信不指定签名时,系统默认使用该签名 |
DefaultSignatureServiceID | 默认签名的唯一特服号 |
SignatureCount | 本账号下短信签名的数量 |
Signature(x) | 根据SignatureCount的数量,通过<Signature(x)></Signature(x)>的形式返回多个短信签名的详细信息 |
Signature(x)/Signature | 短信签名的内容 |
Signature(x)/Status | 短信签名的审核状态,Ready表示可用 |
Signature(x)/ServiceID | 与短信签名匹配的唯一特服务号 |
Signature(x)/OrganizationName | 使用该短信签名的单位/组织名称 |
Signature(x)/Description | 备注/说明信息 |
回调消息推送地址的配置:
如果用户在管理平台的“业务管理”-“回调消息地址配置”中,配置了“短信状态报告”和“短信上行(回复)信息”的回调消息地址,则当有这两类消息触发时,云信使系统会将消息的详情推送到用户所配置的地址。该地址的配置如下图所示:
用户亦可在每次发送短信时动态变更状态报告回调消息的接收地址,如需实现该动态变更功能,请咨询技术客服。
用户系统接收后的响应:
用户系统成功接收消息后,返回字符串0。云信使系统如果未收到字符串0,则认为推送失败,会再次推送该消息(最多三次)。
消息说明:
当云信使系统收到手机用户的回复信息时,实时向用户系统推送该条回复消息,用户系统拆解所收到XML数据包即可获取详情。
用户系统接收的XML数据包:
<xml>
<PushSN></PushSN>
<UserName></UserName>
<Business>SMS</Business>
<Event>MO</Event>
<FromPhone></FromPhone>
<ToNumber></ToNumber>
<Signature></Signature>
<Content></Content>
<ReceiveTime></ReceiveTime>
<Time></Time>
</xml>
接收的XML数据包参数说明:
参数 | 含义 |
---|---|
PushSN | 该消息的序列号,如果由于意外原因导致服务器需要重发该消息,该序列号不变 |
UserName | 归属的账户名 |
Business | 固定值SMS,表明这是一个短信应用的回调消息 |
Event | 固定值MO,表明这是短信应用消息中收到回复的短信的事件 |
FromPhone | 回复短信的手机号码 |
ToNumber | 接收短信的特服号码 |
Signature | 本次回复归属的短信签名 |
Content | 接收短信的内容 |
ReceiveTime | 接收的时间 |
Time | 该事件触发的时间 |
消息说明:
当云信使系统收到运营商的发送状态报告时,实时向用户系统推送该条状态报告,用户系统拆解所收到XML数据包即可获取详情。
用户系统接收的XML数据包:
<xml>
<PushSN></PushSN>
<UserName></UserName>
<Business>SMS</Business>
<Event>Report</Event>
<SN></SN>
<Phone></Phone>
<Status></Status>
<SubmitTime></SubmitTime>
<SendTime></SendTime>
<ReceiveTime></ReceiveTime>
<Time></Time>
</xml>
接收的XML数据包参数说明:
参数 | 含义 |
---|---|
PushSN | 该消息的序列号,如果由于意外原因导致服务器需要重发该消息,该序列号不变 |
UserName | 归属的账户名 |
Business | 固定值SMS,表明这是一个短信应用的回调消息 |
Event | 固定值Report,表明这是短信应用消息中收到短信状态报告的事件 |
SN | 该条短信所在的批次的序列号 |
Phone | 查询的手机号码 |
Status | 运营商的状态报告 ,根据该值可以判断接收状态 |
SubmitTime | 短信提交的时间 |
SendTime | 短信实际发送的时间 |
ReceiveTime | 接收到运营商状态报告的时间 |
Time | 该事件触发的时间 |
用户可以登录帮客云信使业务管理系统(https://www.yunxinshi.com/user/),通过“接口调试工具”--“短信应用”模块,快速测试与调试本功能。调试工具如下图所示: