驗證碼下發

最新更新:2024-03-08

本接口由 EngageLab 平台生成驗證碼,並按照模板中指定的通道策略下發。

如果您希望自行生成驗證碼而不通過 EngageLab 平台生成,可以調用 EngageLab OTP 自定義驗證碼下發 接口。

调用地址

POST https://otp.api.engagelab.cc/v1/messages

调用验证

采用 HTTP 基本认证 的验证方式,在 HTTP Header(头)里加 Authorization:

Authorization: Basic ${base64_auth_string}
          Authorization: Basic ${base64_auth_string}

        
此代碼塊在浮窗中顯示

上述 base64_auth_string 的生成算法为:base64(dev_key:dev_secret)

请求示例

请求头

POST /v1/messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
          POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

        
此代碼塊在浮窗中顯示

请求体

{ "to": "+8618701235678", "template":{ "id":"test-template-1", "language": "default", "params": { "key1": "value1", "key2": "value2" } } }
          {
    "to": "+8618701235678",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

        
此代碼塊在浮窗中顯示

请求参数

一个请求对象以 JSON 格式表达,因此请求头需要带 Content-Type: application/json 。

参数 类型 选项 说明
to String 必填 发送目标,手机号或邮箱地址,+8613800138000,support@engagelab.com
template JSON Object 必填 模板信息,所含二级参数见下方
|_ id String 必填 模板 ID
|_ language String 可选 模板語言,支援以下幾種語言:
default 預設語言
zh_CN 簡體中文
zh_HK 繁體中文
en 英文
ja 日文
th 泰文
es 西班牙文
若未指定,將預設為「default」(預設語言)。
|_ params JSON Object 可选 自定义模板变量 Key的取值
如果您在创建模板时自定义了变量,则在此为它们传值,若不传,则将直接以变量Key下发,如{{var}}

对于params的说明

  1. 对于模版有预设的字段如from_id,若不传param_vars字段值,则消息下发时使用模版预设的from_id;
  2. 若传递了param_vars字段值,如param_vars:{"from_id":"12345"},则消息下发时,模版的from_id将会替换成12345;
  3. 同时对于创建模版时模版内容有自定义的变量字段,也都通过param_vars进行赋值,如模版内容Hi {{name}}, your verify code is {{code}},此时需要赋值参数param_vars:{"name":"Bob"}

返回参数

成功返回

字段 类型 选项 描述
message_id String 必填 消息 ID,唯一标识某一条消息
send_channel String 必填 表示当前下发的通道,取值有whatsapp/sms/email/voice
{ "message_id": "1725407449772531712", "send_channel": "sms" }
          {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

        
此代碼塊在浮窗中顯示

注意,返回的**send_channel**值不代表最终下发到用户的通道,仅代表现阶段使用的通道;如模版配置的策略中配置了WhatsApp通道送达失败然后自动补发SMS通道,则接口返回将返回whatsapp值,一定时间后感知到送达失败,系统将采用SMS通道发送

失败返回

http 状态码为 4xx 或者 5xx,响应体包含字段如下:

字段 类型 选项 描述
code int 必填 错误码,详见 错误码说明
message String 必填 错误详情
{ "code": 5001, "message": "sms send fail" }
          {
    "code": 5001,
    "message": "sms send fail"
}

        
此代碼塊在浮窗中顯示

错误码

错误码 http code 说明
1000 500 内部错误
2001 401 鉴权失败,未携带正确的 token
2002 401 鉴权失败,token已过期或已被禁用
2004 403 无调用此 API 的权限
3001 400 请求参数格式无效,请检查是否符合参数格式的 JSON 内容
3002 400 请求参数有误,请检查请求参数是否符合要求
3003 400 请求参数有误,相关业务校验失败,详情参考 message 字段的错误描述
3004 400 超出频率限制,针对同一模版以及同一目标用户,在验证码的有效期内无法再次下发
4001 400 相关资源不存在,如模版消息下发时使用了不存在的模版
5001 400 验证码消息下发失败,详情参考 message 字段的错误描述
在文档中心打开
icon
聯繫銷售