自訂訊息下發
如果您在 OTP 平台建立了自訂範本內容，則呼叫此 API 發送自訂訊息內容。
呼叫地址
POST https://otp.api.engagelab.cc/v1/custom-messages
呼叫驗證
請參考 呼叫驗證 了解如何進行 API 鑑權。
請求格式
請求頭
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": "+6591234567",
"template":{
"id":"test-template-1",
"params": {
"code": "codevalue",
"var1":"value1"
}
}
}
{
"to": "+6591234567",
"template":{
"id":"test-template-1",
"params": {
"code": "codevalue",
"var1":"value1"
}
}
}
此代碼塊在浮窗中顯示
請求參數
一個請求物件以 JSON 格式表達，因此請求頭需要帶 Content-Type: application/json 。
| 參數 | 類型 | 選項 | 說明 |
|---|---|---|---|
| to | String | 必填 | 發送目標，手機號碼或電子信箱地址，+6598765432，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"} - Email 管道特殊變數：對於 Email 管道，支援透過
params動態覆蓋郵件主旨（subject）、發件人名稱（from_name）、發件人信箱（from_mail）等。詳細的進階用法請參考 建立範本 - Email 範本變數進階用法。
請求範例
1. 發送自訂驗證碼：
{
"to": "+6591234567",
"template":{
"id":"code-template",
"params": {
"code": "123456"
}
}
}
{
"to": "+6591234567",
"template":{
"id":"code-template",
"params": {
"code": "123456"
}
}
}
此代碼塊在浮窗中顯示
2. 發送自訂通知內容：
{
"to": "+6591234567",
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": "+6591234567",
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
此代碼塊在浮窗中顯示
3. 發送自訂行銷內容：
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"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 管道，則 API 返回將返回 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 | 發送失敗（通用/其他） |
| 5011 | 400 | 手機號碼格式無效 |
| 5012 | 400 | 目標不可達 |
| 5013 | 400 | 號碼被加入黑名單 |
| 5014 | 400 | 內容不符合規範 |
| 5015 | 400 | 訊息被攔截/拒絕 |
| 5016 | 400 | 發送內部錯誤 |
| 5017 | 400 | 無中國地區發送權限 |
| 5018 | 400 | 手機故障（關機/停機） |
| 5019 | 400 | 用戶已退訂 |
| 5020 | 400 | 號碼未註冊/空號 |
