通過 API 發送短信
若您希望自動化發送通知和行銷短信，而不通過 EngageLab 平台生成，可以調用本接口。指定短信模版 ID 及目標收件人，系統將自動按模版內容發送短信。
平台配置
調用前，需要在 EngageLab SMS 控制台完成以下配置：
短信模版設置：在調用 API 前，請先前往模版管理頁面，自定義並提交短信模版。模版需通過審核後，方可使用模版 ID。
API 鑰匙配置：前往API 鑰匙頁面，創建 API Basic 鑑權鑰匙。
調用流程
請參考以下流程調用 API 發送短信，如有疑問，請聯繫客服。
調用地址
POST https://smsapi.engagelab.com/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": [
"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 。
| 名稱 | 位置 | 類型 | 必選 | 中文名 | 說明 |
|---|---|---|---|---|---|
| Authorization | header | array[string] | 否 | ||
| to | body | array[string] | 是 | 發送的id list | 發送目標手機號 |
| plan_name | body | string | 否 | 計劃名稱 | 非必填,不填默認顯示"-" |
| schedule_time | body | integer | 否 | 定時發送的時間 | 非定時發送不傳該參數，時間戳 |
| template | body | object | 是 | ||
| id | body | string | 是 | ||
| params | body | object | 是 | ||
| custom_args | body | object | 否 | 自定義參數 |
如果您在創建模板時自定義了變量，則在此為它們傳值，若不傳，則將直接以變量Key下發，如{{var1}} |
對於params的說明
同時對於創建模板時模板內容有自定義的變量字段，也都通過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，響應體包含字段如下：
| 字段 | 類型 | 選項 | 描述 |
|---|---|---|---|
| plan_id | string | 必需 | 計劃id |
| total_count | integer | 必需 | 接收到的目標數量 |
| accepted_count | integer | 必需 | 接收到的有效目標數量 |
| message_id | string | 可選 | 單個發送的時候會返回對應的 message_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
}
}
此代碼塊在浮窗中顯示
異常示例
{
"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 狀態碼為 200，響應體包含字段如下：
| 字段 | 類型 | 說明 |
|---|---|---|
| plan_id | string | 必填 |
| total_count | integer | 必填 |
| accepted_count | integer | 必填 |
| message | string | 必填 |
| code | integer | 必填 |
{
"plan_id": "string",
"total_count": 0,
"accepted_count": 0,
"message": "string",
"code": 0
}
{
"plan_id": "string",
"total_count": 0,
"accepted_count": 0,
"message": "string",
"code": 0
}
此代碼塊在浮窗中顯示
錯誤碼
| 錯誤碼 | 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 字段的錯誤描述 |
