自定义消息下发

如果您在OTP平台创建了自定义模板内容，则调用此接口发送自定义消息内容。

调用地址

POST https://otp.api.engagelab.cc/v1/custom-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/custom-messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

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

此代码块在浮窗中显示

请求体

{ "to": "+8618701235678", "template":{ "id":"test-template-1", "params": { "code": "codevalue", "var1":"value1" } } }

          {
    "to": "+8618701235678", 
    "template":{
      "id":"test-template-1",
      "params": {
        "code": "codevalue",
        "var1":"value1"
        }
    }
}

此代码块在浮窗中显示

请求参数

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

参数	类型	选项	说明
to	String	必填	发送目标，手机号或邮箱地址，+8613800138000，support@engagelab.com
template	JSON Object	必填	模板信息，所含二级参数见下方
\|_ id	String	必填	模板 ID
\|_ params	JSON Object	可选	模板参数
_ \|_ code	String	可选	模板类型为验证码时，该字段必填。
_ \|_ var	String	可选	自定义模板变量 Key的取值
如果您在创建模板时自定义了变量，则在此为它们传值，若不传，则将直接以变量Key下发，如{{var1}}

对于`params`的说明

对于{{brand_name}}，{{ttl}}，{{pwa_url}} 等模版预设变量，不需要传递，系统会自动替换为模板创建时指定的内容；
如果模板类型为验证码，则必须要传递{{code}}变量，否则会报错。；
同时对于创建模版时模版内容有自定义的变量字段，也都通过params进行赋值，如模版内容Hi {{name}}, your verify code is {{code}}，此时需要赋值参数params:{"name":"Bob"}

请求示例

1. 发送自定义验证码：

{ "to": "+8618701235678", "template":{ "id":"code-template", "params": { "code": "123456" } } }

          {
    "to": "+8618701235678", 
    "template":{
      "id":"code-template",
      "params": {
        "code": "123456"        
        }
    }
}

此代码块在浮窗中显示

2. 发送自定义通知内容：

{ "to": "+8618701235678", "template":{ "id":"notification-template", "params": { "order":"123456" } } }

          {
    "to": "+8618701235678", 
    "template":{
      "id":"notification-template",
      "params": {       
        "order":"123456"
        }
    }
}

此代码块在浮窗中显示

3. 发送自定义营销内容：

{ "to": "+8618701235678", "template":{ "id":"marketing-template", "params": { "name":"EngageLab", "promotion":"30%" } } }

          {
    "to": "+8618701235678", 
    "template":{
      "id":"marketing-template",
      "params": {       
        "name":"EngageLab",
        "promotion":"30%"
        }
    }
}

此代码块在浮窗中显示

返回参数

成功返回

字段	类型	选项	描述
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 字段的错误描述

自定义消息下发

调用地址

调用验证

请求格式

请求头

请求体

请求参数

对于params的说明

请求示例

1. 发送自定义验证码：

2. 发送自定义通知内容：

3. 发送自定义营销内容：

返回参数

成功返回

失败返回

错误码

对于`params`的说明