Send SMS
If you wish to automate the sending of notifications and marketing SMS, you can call this API. Specify the SMS template ID and target recipients, and the system will automatically send SMS messages based on the template content.
Platform Configuration Prompt Before calling, you need to complete the following configuration in the EngageLab SMS Console:
- SMS Template Settings: Before calling the API, please go to Template Management to customize and submit an SMS template. The template must pass the review before you can use the template ID.
- API Key Configuration: Go to API Key to create an API Basic authentication key.
Request URL
POST https://smsapi.engagelab.com/v1/messages
Call Authentication
Please refer to Call Authentication to learn how to authenticate API requests.
Request Example
Request Header
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
This code block in the floating window
Request Body
{
"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."
}
}
}
This code block in the floating window
Request Parameters
A request object is expressed in JSON format, so the request header must include Content-Type: application/json.
| Parameter | Type | Option | Description |
|---|---|---|---|
| to | Array[String] | Required | List of target mobile numbers to send to, e.g., ["923700056581"] |
| plan_name | String | Optional | Plan name, defaults to "-" if not filled |
| schedule_time | Integer | Optional | The time for scheduled sending. Do not pass this parameter for non-scheduled sending. Unix timestamp, in "seconds". Validation rules: Must be a positive number; must be strictly at least 3 minutes later than the current time; cannot exceed 30 days from the current time. |
| template | JSON Object | Required | Template information, see below for nested parameters |
| |_ id | String | Required | Template ID |
| |_ params | JSON Object | Required | Values of custom template variable keys If you customized variables when creating the template, pass values for them here. If not passed, they will be delivered directly as variable keys, such as {{var1}} |
| custom_args | JSON Object | Optional | Custom parameters |
Description of params
For custom variable fields in the template content when creating a template, they must be assigned via params. For example, if the template content is Hi {{name}}, welcome to EngageLab, you need to assign the parameter params: {"name": "Bob"}.
More Request Examples
1. Send custom notification content:
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
This code block in the floating window
2. Send custom marketing content:
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
This code block in the floating window
Response Parameters
Success Response
The HTTP status code is 200, and the response body contains the following fields:
| Field | Type | Option | Description |
|---|---|---|---|
| plan_id | String | Required | Plan ID |
| total_count | Integer | Required | Number of targets received |
| accepted_count | Integer | Required | Number of valid targets received |
| message_id | String | Optional | Returned during single sending, indicating the corresponding message_id |
| schedule_info | JSON Object | Optional | Relevant information of the scheduled task (returned only for scheduled sending) |
| |_ task_id | Integer | Required | Scheduled task ID |
Success Example (Single Target)
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
This code block in the floating window
Success Example (Multiple Targets)
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
This code block in the floating window
Success Example (Scheduled Task)
{
"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
}
}
This code block in the floating window
Error Response
The HTTP status code is 200 (for some exception cases) or 4xx/5xx, and the response body contains the following fields:
| Field | Type | Option | Description |
|---|---|---|---|
| plan_id | String | Required | Plan ID |
| total_count | Integer | Required | Number of targets received |
| accepted_count | Integer | Required | Number of valid targets received |
| code | Integer | Required | Error code, see error code description for details |
| message | String | Required | Error details |
Error Example
{
"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
}
This code block in the floating window
Error Codes
| Error Code | HTTP Code | Description |
|---|---|---|
| 1000 | 500 | Internal error |
| 2001 | 401 | Authentication failed, incorrect token provided |
| 2002 | 401 | Authentication failed, token expired or disabled |
| 2004 | 403 | No permission to call this API |
| 3001 | 400 | Invalid request parameter format, please check if it conforms to the required JSON format |
| 3002 | 400 | Request parameters are incorrect, please check if they meet the requirements |
| 3003 | 400 | Request parameters are incorrect, relevant business verification failed. Refer to the error description in the message field for details. |
| 3004 | 400 | Exceeded frequency limit, cannot send again to the same target user with the same template within the validity period of the verification code |
| 4001 | 400 | Related resource does not exist, e.g., used a non-existent template during message delivery |
| 5001 | 400 | Message delivery failed. Refer to the error description in the message field for details. |
