# 短信通知接口 #### 接口功能 隐私保护通话平台通过此接口向客户服务器推送隐私号短信通知。 通知模式分为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"不能去除。 #### 请求方向 隐私保护通话平台（服务端） → 客户服务器（客户端） #### 使用说明 前提条件 - 客户[添加应用](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_01.html)时需设置短信通知接收地址，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。 - 若需要接收用户发送的短信内容，请参考[如何设置才能收到短信内容？](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_00046.html)进行设置。 - 短信通知重传功能为默认开启，该功能开启后，当隐私保护通话平台推送短信事件通知给客户服务器失败时，隐私保护通话平台会重传事件通知给客户服务器。最多重传6次，每次重传时间间隔可由系统管理员设置。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限管理](https://support.huaweicloud.com/productdesc-PrivateNumber/privatenumber_permissions.html)。 #### 接口类型 表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] | 短信状态事件。 | 表5SMSEventInfoType定义 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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) | 用户发送的短信内容。 请参考[如何设置才能收到短信内容？](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_00046.html)开通该功能。 | | sendResult | 是 | Integer | 发送结果。 - 0：成功 - 1：因用户账户冻结，发送失败。 - 2：因绑定关系不存在，发送失败。 - 3：因X号码被暂停，发送失败。 - 4：非商用APP，发送失败。 - 5：因系统内部错误，发送失败。 - 6：SP指示丢弃，发送失败。 - 7：等待SP审核超时丢弃，发送失败。 - 8：黑名单管控，发送失败。 - 9：部分发送成功。 - 10：全部发送失败。 - 11：X号码不支持短信能力。 - 12：短信内容不包含特征关键词。 - 13：短信内容包含禁止词汇。 - 16： 从业者未实名 | | areaCode | 否 | String(0-32) | 隐私保护号码（X号码）的城市码。 说明： 使用该参数的场景请联系华为云客服获取。 | | userData | 否 | String(1-256) | 用户附属信息。 说明： 使用该参数的场景请联系华为云客服获取。 | 表6ExtensionInfoType定义 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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\[\]] | 短信操作指示。 | 表8SMSActionType定义 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | operation | 是 | String(1-32) | 操作类型： - vNumberRoute：转发短信。 - DiscardMessage：丢弃短信。 | | message | 否 | [MessageInfo] | 短信操作信息。 仅当operation取值为"vNumberRoute"时有效。 | | extParas | 否 | JsonArray | 预留参数，当前版本无需关注。 | | userData | 否 | String(1-256) | 用户自定义数据。 - 不允许携带以下字符："{"，"}"（即大括号）。 - 不允许包含中文字符，如果包含中文字符请采用Base64编码。 说明： 使用该参数的场景请联系华为云客服获取。 | 表9MessageInfo定义 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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" } }] } ```