自定義消息下發
如果您在OTP平台創建了自定義模板內容，則調用此接口發送自定義消息內容。
調用地址
POST https://otp.api.engagelab.cc/v1/custom-messages
調用驗證
採用 HTTP 基本認證](http://zh.wikipedia.org/wiki/HTTP%E5%9F%BA%E6%9C%AC%E8%AE%A4%E8%AF%81) 驗證方式，在 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 字段的錯誤描述 |
