WhatsApp OTP Api接口文档(V1.0)

1.前言

创蓝WhatsApp OTP 平台为企业客户对接发送Meta WhatsApp 验证码消息，提供统一Api接口技术支持。本协议统一数据编码格式为:UTF-8。接口采用:HTTPS ，且TLS协议版本 >=1.2，接口用户认证采用请求头sign认证，具体看2.1 公共请求头。

1.1 名词解释

名称	说明
appKey	ApiKey,在开发者工具(Developer Tools)-应用管理(API Keys)中创建查看
appSecret	ApiPassword,在开发者工具(Developer Tools)-应用管理(API Keys)中创建查看
nonce	随机安全码，通常为时间戳，用于签名校验时混淆签名，防止签名被劫持篡改
signature	签名认证，用于用户每次发送数据请求合法校验
sender	WhatsApp Business 账号绑定的号码, WhasApp消息显示的手机号码
to	接收者的手机号码
requestBody	如果请求方式为POST请求，一般为请求报文(JSON 参数)，如果请求方式为GET请求或者上传文件，该字段通常为空字符串，即:""

2.接口定义

2.1 公共请求头

为了保证接口安全，所有的接口，都需要带上请求头，其中appKey和appSecret由创蓝提供,用于接口认证校验，如验证失败，则返回认证失败。

序号	字段	数据类型	是否必填	描述
1	Content-Type	String	是	值为"application/json;charset=utf-8",请求内容为json
2	x-appKey	String	是	ApiKey,在开发者工具(Developer Tools)-应用管理(API Keys)中创建查看
3	x-nonce	String	是	随机安全码
4	x-timestamp	String	是	通常为时间戳
5	x-signature	String	是	签名认证，查看：附2:签名加密

2.1.1 请求示例

content-type: application/json;charset=utf-8 
x-appKey: XFbZY1rtTKo3UD4n
x-nonce: 1621590266536
x-timestamp: 1621590266536
x-signature: c577fd33dc010f03a798d5aawe1caswc

2.2 消息（Message）

2.2.1 发送消息（Send Message）

2.2.1.1 请求接口

请求方式	地址
POST	https://otpapi.tig253.com/otp/api/msg/v1/send

2.2.1.2 请求参数

字段	数据类型	是否必填	描述
templateId	String	是	OTP模板(策略)ID
language	String	是	模板语言,查看附1:语言编码
to	String	是	接收手机号码
code	String	是	验证码
sender	String	否	WhatsApp Sender(显示号码,未绑定号码会失败)

2.2.1.3 请求示例

{
    "templateId":"110129512080522",
    "language":"en",
    "to": "8618912123457",
    "code": "123213",
    "sender": "8618912123456"
}

2.2.1.4 响应示例

{
    "code": "0",
    "message": "Success",
    "reqId": "1101295120805221231231",
    "data":"2342623234234234234"  //消息的messageId
}

2.2.2 状态报告

2.2.2.1 状态推送

用户在OPT平台配置推送地址，状态报告会通过此地址推送到客户系统

字段	数据类型	是否必填	描述
accountNo	String	是	产品账号
appKey	String	是	应用KEY
messageId	String	是	消息ID
mobile	String	是	手机号码
status	String	是	状态 0: 进行中，1:失败，2:成功
code	String	是	Code success: 成功， failed :失败
reportTime	String	是	状态报告时间 yyyy-MM-dd HH:mm:ss
channelName	String	否	通道名称

{
    "accountNo":"110129512080522",
    "appKey": "6285234567899",
    "messageId": "8618912123456",
    "mobile": "861571111111",
    "status":"0",
    "code":"success",
    "reportTime":"2024-12-12 11:12:12",
    "channelName":"whatsApp"
}