更新时间:2023-01-13 GMT+08:00
分享

X号码状态通知接口

接口功能

X号码状态变化时,隐私保护通话平台会向客户推送通知。号码状态变化包括:
  • 因号码删除、欠费、停机,号码状态从可用变为不可用;
  • 号码状态从不可用恢复为可用;
  • 不可用原因变化,例如从欠费变为停机。

请求方向

隐私保护通话平台(服务端) → 客户服务器(客户端)

使用说明

  • 前提条件

    客户添加应用时需设置呼叫状态接收地址并启用推送X号码状态功能,并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。

    注:若需单独接收X号码状态通知,需填写X号码状态接收地址。呼叫状态接收地址X号码状态接收地址都填写了,隐私保护通话平台会向呼叫状态接收地址推送呼叫事件通知,向X号码状态接收地址推送X号码状态通知。

  • 使用限制

    业务平台推送呼叫状态给开发者应用,仅支持POST方式。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

客户添加应用时填写的呼叫状态接收地址/X号码状态接收地址

通信协议

HTTPS/HTTP

请求参数

表2 请求Headers参数说明

参数名称

是否必选

参数类型

说明

Content-Type

String

固定填写为application/json;charset=UTF-8。

Authorization

String

固定填写为WSSE realm="SDP",profile="UsernameToken",type="Appkey"。

X-WSSE

String

取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
  • PasswordDigest:根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成。其中,Password为APP_Secret的值。Nonce、Created、Password直接进行字符串拼接即可,无需包含+号和空格。
  • Nonce:客户发送请求时生成的一个随机数,长度为1~128位,可包含数字和大小写字母。例如:66C92B11FF8A425FB8D4CCFE0ED9ED1F。
  • Created:随机数生成时间。采用标准UTC格式,例如:2018-02-12T15:30:20Z。不同编程语言中将UTC时间戳转换为普通时间时使用的格式不同,部分语言可参考表3
表3 不同编程语言的时间格式

编程语言

时间格式

Java

yyyy-MM-dd'T'HH:mm:ss'Z'

PHP

Y-m-d\TH:i:s\Z

Python

%Y-%m-%dT%H:%M:%SZ

C#

yyyy-MM-ddTHH:mm:ssZ

Node.js

toISOString().replace(/.[0-9]+\Z/, 'Z')

注:Node.js中,使用toISOString()转换后的时间格式去除毫秒后即为本接口要求的时间格式。

表4 请求Body参数说明

参数名称

是否必选

参数类型

说明

eventType

String(枚举)

该参数标识通知的事件类型。

取值范围如下:

  • numStatus:X号码状态变化

numInfo

numInfo [1-100]

X号码状态变化事件的信息,参数取值为列表,最大100条。

当eventType参数为numStatus时携带。

表5 numInfo定义

参数名称

是否必须

参数类型

说明

number

String

状态变化的X号码。

status

String

号码状态。

  • 5:正常
  • 9:暂停
  • 10:不可用
  • 11:冻结绑定
说明:

各号码状态对业务的影响如下:

  • 正常:无影响。
  • 暂停&不可用:绑定、呼叫和短信都不可用。
  • 冻结绑定:号码不可新增绑定关系,但已存在的绑定关系的呼叫和短信业务不受影响。

cause

String

号码不可用原因。仅status为不可用时携带。

  • 1:号码已删除
  • 2:欠费
  • 3:停机
  • 5:X号码被运营商限呼
  • 6:X号码限呼恢复
  • 7:X号码开通了无条件前转业务
  • 8:X号码开通了无应答前转业务
  • 9:X号码开通了被叫忙前转业务

接口示例

POST /Xnumber/status HTTP/1.1

content-type: application/json;charset=UTF-8
authorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"
x-wsse: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
content-length:xx

{"eventType":"numStatus","numInfo":[{"number":"+86156****0000","status":"9"}]}

响应参数

客户服务器接收到隐私保护通话平台的X号码状态变化通知后,返回的响应消息。

接口示例

HTTP/1.1 200 OK 

相关文档