自訂訊息發送
如果您已在 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": "+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"}
請求範例
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 通道，則介面回傳將會是 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 | 號碼未註冊／空號 |
