發送簡訊
若您希望自動化發送通知和行銷簡訊，可以呼叫本介面。指定簡訊範本 ID 及目標收件人，系統將自動按範本內容發送簡訊。
平台設定提示 呼叫前，需要在 EngageLab SMS 控制台完成以下設定：
呼叫位址
POST https://smsapi.engagelab.com/v1/messages
呼叫驗證
請參考 呼叫驗證 了解如何進行 API 驗證。
請求範例
請求標頭
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
此代碼塊在浮窗中顯示
請求主體
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
此代碼塊在浮窗中顯示
請求參數
一個請求物件以 JSON 格式表達，因此請求標頭需要帶 Content-Type: application/json。
| 參數 | 類型 | 選項 | 說明 |
|---|---|---|---|
| to | Array[String] | 必填 | 發送目標手機號碼列表，如 ["923700056581"] |
| plan_name | String | 可選 | 計畫名稱，不填預設顯示 "-" |
| schedule_time | Integer | 可選 | 定時發送的時間。非定時發送不傳該參數。Unix 時間戳記，單位是「秒」。 校驗規則：必須為正數；必須嚴格晚於當前時刻至少 3 分鐘；不能超過從當前時刻起 30 天。 |
| template | JSON Object | 必填 | 範本資訊，所含二級參數見下方 |
| |_ id | String | 必填 | 範本 ID |
| |_ params | JSON Object | 必填 | 自訂範本變數 Key 的取值 如果您在建立範本時自訂了變數，則在此為它們傳值，若不傳，則將直接以變數 Key 下發，如 {{var1}} |
| custom_args | JSON Object | 可選 | 自訂參數 |
對於 params 的說明
對於建立範本時範本內容有自訂的變數欄位，都需要透過 params 進行賦值。例如範本內容為 Hi {{name}}, welcome to EngageLab，此時需要賦值參數 params: {"name": "Bob"}。
更多請求範例
1. 發送自訂通知內容：
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
此代碼塊在浮窗中顯示
2. 發送自訂行銷內容：
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
此代碼塊在浮窗中顯示
回傳參數
成功返回
http 狀態碼為 200，回應主體包含欄位如下：
| 欄位 | 類型 | 選項 | 描述 |
|---|---|---|---|
| plan_id | String | 必填 | 計畫 ID |
| total_count | Integer | 必填 | 接收到的目標數量 |
| accepted_count | Integer | 必填 | 接收到的有效目標數量 |
| message_id | String | 可選 | 單個發送的時候會回傳對應的 message_id |
| schedule_info | JSON Object | 可選 | 定時任務的相關資訊（僅定時發送時回傳） |
| |_ task_id | Integer | 必填 | 定時任務 ID |
成功範例（單目標）
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
此代碼塊在浮窗中顯示
成功範例（多目標）
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
此代碼塊在浮窗中顯示
成功範例（定時任務）
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
此代碼塊在浮窗中顯示
失敗返回
http 狀態碼為 200（部分異常情況）或 4xx/5xx，回應主體包含欄位如下：
| 欄位 | 類型 | 選項 | 描述 |
|---|---|---|---|
| plan_id | String | 必填 | 計畫 ID |
| total_count | Integer | 必填 | 接收到的目標數量 |
| accepted_count | Integer | 必填 | 接收到的有效目標數量 |
| code | Integer | 必填 | 錯誤碼，詳見錯誤碼說明 |
| message | String | 必填 | 錯誤詳情 |
異常範例
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
此代碼塊在浮窗中顯示
錯誤碼
| 錯誤碼 | 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 欄位的錯誤描述 |
