验证码下发

本接口由 EngageLab 平台生成验证码，并按照模板中指定的通道策略下发。

如果您希望自行生成验证码而不通过 EngageLab 平台生成，可以调用 EngageLab OTP 自定义验证码下发 接口。

调用地址

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

调用验证

请参考 调用验证 了解如何进行 API 鉴权。

请求示例

请求头

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

            

请求体

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

            

请求参数

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

对于params的说明

1. 对于模版有预设的字段如 from_id，若不传 params 字段值，则消息下发时使用模版预设的 from_id；
2. 若传递了 params 字段值，如params:{"from_id":"12345"}，则消息下发时，模版的 from_id 将会替换成 12345；
3. 同时对于创建模版时模版内容有自定义的变量字段，也都通过 params 进行赋值，如模版内容Hi {{name}}, your verify code is {{code}}，此时需要赋值参数params:{"name":"Bob"}
4. Email 通道特殊变量：对于 Email 通道，支持通过 params 动态覆盖邮件主题（subject）、发件人名称（from_name）、发件人邮箱（from_mail）等。详细的高级用法请参考 创建模板 - Email 模板变量高级用法。

返回参数

成功返回

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

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

失败返回

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

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

错误码

下表仅描述本接口在鉴权、发送前校验和同步提交阶段返回的错误。供应商受理后的异步送达失败不通过本接口返回，请通过消息状态查询或回调获取。

调用方应以 code 判断错误类型，message 用于展示具体原因或辅助排查，不建议依赖固定的 message 文案编写业务逻辑。

限流及发送量错误说明

• 3004 是模板验证码下发频控，限制窗口以模板配置为准，不一定等于验证码有效期。
• 6001、6002 是号码或终端用户 IP 维度的安全频控。
• 6003、6008 表示本次请求触发了发送量上限；达到上限并进入暂停状态后，后续请求可能返回 6007。
• 收到 HTTP 429 时，请勿立即连续重试；请稍后重试，如持续出现，请联系管理员或技术支持。
• 5011 至 5019 只表示同步提交阶段能够识别的失败。供应商受理后产生的空号、关机、运营商拒绝等状态，仍可能通过异步消息状态或回调返回。