通過 API 發送短信
若您希望自動化發送通知和行銷短信，而不通過 EngageLab 平台生成，可以調用本接口。指定短信模版 ID 及目標收件人，系統將自動按模版內容發送短信。
平台配置
調用前，需要在 EngageLab NewSMS 控制台完成以下配置：
短信模版設置：在調用 API 前，請先前往模版管理頁面，自定義並提交短信模版。模版需通過審核後，方可使用模版 ID。
API 鑰匙配置：前往API 鑰匙頁面，創建 API Basic 鑑權鑰匙。
調用流程
請參考以下流程調用 API 發送短信，如有疑問，請聯繫客服。
調用地址
POST https://smsapi.engagelab.cc/v1/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/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_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "erification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
{
"to_ids": [
"8613138283670"
],
"plan_name": "test",
"template": {
"id": 1970314609822883800,
"language": "en",
"params": {
"content": "erification code: 039487, will expire in 5 minutes. You are trying to create your"
}
},
"source": 1
}
此代碼塊在浮窗中顯示
請求參數
一個請求對象以 JSON 格式表達，因此請求頭需要帶 Content-Type: application/json 。
| 名稱 | 位置 | 類型 | 必選 | 中文名 | 說明 |
|---|---|---|---|---|---|
| Authorization | header | array[string] | 否 | none | |
| body | body | object | 否 | none | |
| » to_ids | body | [string] | 是 | 發送的id list | 如果只有一個就傳一個就可以了 |
| » plan_name | body | string | 否 | 計劃名稱 | 非必填,不填默認顯示"-" |
| » schedule_time | body | integer | 否 | 定時發送的時間 | 非定時發送不傳該參數，時間戳 |
| » template | body | object | 是 | ||
| »» id | body | string | 是 | none | |
| »» language | body | string | 是 | none | |
| »» params | body | object | 是 | none | |
| »»» custom_param | body | string | 是 | none | |
| » custom_args | body | object | 是 | 自定義參數 |
如果您在創建模版時自定義了變量，則在此為它們傳值，若不傳，則將直接以變量Key下發，如{{var1}} |
對於params的說明
- 對於{{brand_name}}，{{ttl}}，{{pwa_url}} 等模版預設變量，不需要傳遞，系統會自動替換為模版創建時指定的內容；
- 同時對於創建模版時模版內容有自定義的變量字段，也都通過params進行賦值，如模版內容
Hi {{name}}, welcome to EngageLab，此時需要賦值參數params:{"name":"Bob"}
請求示例
1. 發送自定義通知內容：
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"notification-template",
"params": {
"order":"123456"
}
}
}
此代碼塊在浮窗中顯示
2. 發送自定義行銷內容：
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
{
"to": "+8618701235678",
"template":{
"id":"marketing-template",
"params": {
"name":"EngageLab",
"promotion":"30%"
}
}
}
此代碼塊在浮窗中顯示
返回參數
成功返回
http 狀態碼為 200，響應體包含字段如下：
| 字段 | 類型 | 選項 | 描述 |
|---|---|---|---|
| message_id | String | 必填 | 消息 ID，唯一標識某一條消息 |
| to_id | String | 必填 | 發送的手機號 |
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
{
"to_id": "8613138283670",
"message_id": "1971029055205646336"
}
此代碼塊在浮窗中顯示
失敗返回
http 狀態碼為 4xx 或者 5xx，響應體包含字段如下：
| 字段 | 類型 | 選項 | 描述 |
|---|---|---|---|
| err_code | int | 必填 | 錯誤碼，詳見 錯誤碼說明 |
| err_msg | String | 必填 | 錯誤詳情 |
{
"err_msg": "sms send failed",
"err_code": 10013
}
{
"err_msg": "sms send failed",
"err_code": 10013
}
此代碼塊在浮窗中顯示
錯誤碼
| 錯誤碼 | 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 字段的錯誤描述 |
