文档首页/ 隐私保护通话 PrivateNumber/ API参考/ AX模式/ 短信通知接口
更新时间：2024-11-15 GMT+08:00
查看PDF
分享

短信通知接口

接口功能

隐私保护通话平台通过此接口向客户服务器推送隐私号短信通知。

通知模式分为Notify和Block模式：

  • Notify：通知模式，Notify模式的短信通知会被推送到客户添加应用时填写的短信通知地址，客户收到通知后返回HTTP状态码为200的空消息即可。
  • Block：控制模式，Block模式的短信通知会被推送到客户添加应用时填写的短信控制地址，客户收到通知后需按照Block模式响应参数返回响应，指示隐私保护通话平台转发或丢弃短信。

AX模式发送隐私号短信的流程如下：

  • A发送短信给X，短信内容最后携带“@号码B”，如“@138****0021”（@必须是英文半角字符，号码B根据实际情况替换成真实用户号码，下同），隐私保护通话平台删除短信内容中的“@号码B”后将短信转发给B（发送方号码是X），并推送Notify模式的隐私号短信通知给客户服务器；

    若短信内容中未携带“@号码B”或携带的分隔符或号码格式错误，则隐私保护通话平台推送Block模式的隐私号短信通知给客户服务器，此时客户服务器必须返回响应参数对短信事件进行控制。隐私保护通话平台根据客户服务器返回的结果转发或丢弃隐私号短信；如果操作是转发，转发成功后推送Notify模式的隐私号短信通知给客户服务器。

  • B发送短信给X，隐私保护通话平台在短信最后添加“[From号码B]”后将短信转发给A（发送方号码是X），并推送Notify模式的隐私号短信通知给客户服务器。

注：AX模式，A发送短信给X时需携带“@号码B”，“@号码B”不能去除。

请求方向

隐私保护通话平台（服务端） → 客户服务器（客户端）

使用说明

前提条件

  • 客户添加应用时需设置短信通知接收地址，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。
  • 若需要接收用户发送的短信内容，请参考如何设置才能收到短信内容？进行设置。
  • 短信通知重传功能为默认开启，该功能开启后，当隐私保护通话平台推送短信事件通知给客户服务器失败时，隐私保护通话平台会重传事件通知给客户服务器。最多重传6次，每次重传时间间隔可由系统管理员设置。

接口类型

表1 请求说明

请求方法

POST

访问URI

客户添加应用时填写的短信通知地址/短信控制地址

通信协议

HTTPS

请求参数

表2 请求Headers参数说明

参数名称

是否必选

参数类型

说明

Content-Type

是

String

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

Authorization

是

String

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

X-AKSK

是

String
取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
  • PasswordDigest：根据PasswordDigest = Base64 (HMAC-SHA256 (Password，Nonce + Created))生成。其中，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参数说明

参数名称

是否必选

参数类型

说明

appKey

是

String(1-32)

隐私保护通话应用的APP_Key。

smsEvent

是

SMSEventInfoType

短信状态事件。
表5 SMSEventInfoType定义

参数名称

是否必选

参数类型

说明

smsIdentifier

是

String(1-64)

短信唯一标识。

若用户发送的是长短信，隐私保护通话平台会将长短信的多个分片合并为一个通知上报。

notificationMode

是

String(1-8)

通知模式：

  • Notify：通知模式。
  • Block：控制模式。

calling

否

String(1-32)

真实发送方号码。

号码为全局号码格式（包含国家码），比如+86138****7021。

called

否

String(1-32)

真实接收方号码。

仅在隐私保护通话平台转发短信成功后携带。

号码为全局号码格式（包含国家码），比如+86138****7022。

virtualNumber

否

String(1-32)

X号码。

号码为全局号码格式（包含国家码），比如+86138****0001。

event

是

String(1-16)

短信状态事件。

TextSMS：文本短信

timeStamp

是

String(1-32)

短信事件发生的系统时间戳，UTC时间。

格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

其中SSS是毫秒，“T”和“Z”为固定字符。

extInfo

是

ExtensionInfoType

拓展信息。

subscriptionId

否

String(1-64)

绑定ID。

smsContent

否

String(1-2000)

用户发送的短信内容。

请参考如何设置才能收到短信内容？开通该功能。

sendResult

是

Integer

发送结果。

  • 0：成功
  • 1：因用户账户冻结，发送失败。
  • 2：因绑定关系不存在，发送失败。
  • 3：因X号码被暂停，发送失败。
  • 4：非商用APP，发送失败。
  • 5：因系统内部错误，发送失败。
  • 6：SP指示丢弃，发送失败。
  • 7：等待SP审核超时丢弃，发送失败。
  • 8：黑名单管控，发送失败。
  • 9：部分发送成功。
  • 10：全部发送失败。
  • 11：X号码不支持短信能力。
  • 12：短信内容不包含特征关键词。
  • 13：短信内容包含禁止词汇。

areaCode

否

String(0-32)

隐私保护号码（X号码）的城市码。

说明：

使用该参数的场景请联系华为云客服获取。

userData

否

String(1-256)

用户附属信息。

说明：

使用该参数的场景请联系华为云客服获取。
表6 ExtensionInfoType定义

参数名称

是否必选

参数类型

说明

extParas

是

JsonArray

扩展信息(Key-Value)列表。

格式如下：

"extParas": [{"key": "splitNum","value": "value1"},{"key": "direction","value": "value2"}]

Key、Value取值分别不能超过32个字节。

“key”取值为“splitNum”时表示实际短信发送成功数量，即长短信拆分后的短信数量。value1表示“splitNum”的取值。

“key”取值为“direction”时表示短信发送方向。value2表示“direction”取值，含义如下：

  • 0：其他用户发送短信给A。
  • 1：A发送短信给其他用户。
  • 2：异常场景无法获取发送方向。

响应参数

客户服务器接收到隐私保护通话平台的短信事件通知后，根据不同的模式返回不同响应消息。

  • Notify模式

    返回无消息体的200响应。

  • Block模式

    响应必须参照表7携带消息体，返回对短信事件的处理操作。

    表7 响应消息参数说明

    参数名称

    是否必选

    参数类型

    说明

    actions

    是

    SMSActionType[]

    短信操作指示。
    表8 SMSActionType定义

    参数名称

    是否必选

    参数类型

    说明

    operation

    是

    String(1-32)

    操作类型：

    • vNumberRoute：转发短信。
    • DiscardMessage：丢弃短信。

    message

    否

    MessageInfo

    短信操作信息。

    仅当operation取值为“vNumberRoute”时有效。

    extParas

    否

    JsonArray

    预留参数，当前版本无需关注。

    userData

    否

    String(1-256)

    用户自定义数据。

    • 不允许携带以下字符：“{”，“}”（即大括号）。
    • 不允许包含中文字符，如果包含中文字符请采用Base64编码。
    说明：

    使用该参数的场景请联系华为云客服获取。
    表9 MessageInfo定义

    参数名称

    是否必选

    参数类型

    说明

    called

    否

    String(1-64)

    真实接收方号码。

    号码仅支持全局号码格式（包含国家码），比如+86138****7022。

    calling

    否

    String(1-64)

    真实发送方号码。

    和请求参数中的calling参数的取值保持一致。

    号码仅支持全局号码格式（包含国家码），比如+86138****7021。

接口示例

接口示例仅供参考，请以实际消息为准。
  • notify模式
    请求示例 
    POST /notify HTTP/1.1 

content-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
content-length:xx
  
{
"appKey":"****",
"smsEvent":{"smsIdentifier":"********",
            "notificationMode":"Notify",
            "calling":"+86138****0001",
            "virtualNumber":"+86138****0000",
            "event":"TextSMS",
            "timeStamp":"2020-12-23T09:06:16.450Z",
            "extInfo":{"extParas":[{"key":"splitNum","value":"0"},{"key":"direction","value":"2"}]},
            "sendResult":2
            }
}
    响应示例 
    HTTP/1.1 200 OK

  • Block模式

    请求示例

    POST /block HTTP/1.1
 
content-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
content-length:xx
  
{
"appKey":"****",
"smsEvent":{"smsIdentifier":"****",
            "notificationMode":"Block",
            "calling":"+86138****0001",
            "virtualNumber":"+86138****0000",
            "event":"TextSMS",
            "timeStamp":"2018-09-13T09:46:16.023Z",
            "extInfo":{"extParas":[{"key":"splitNum","value":"2"},{"key": "direction","value": "1"}]},
            "sendResult":0
             }
}
    响应示例 
    HTTP/1.1 200 OK 

 Content-Type: application/JSON;charset=UTF-8 
 Content-Length: xx 
  
{ 
"actions":[{ 
            "operation":"vNumberRoute", 
            "message":{"called":"+86138****0002", 
                       "calling":"+86138****0001"
                      } 
           }] 
 }
父主题： AX模式

相关文档