API SMS Sending

If you wish to automate the sending of notification and marketing SMS without generating them through the EngageLab platform, you can call this API. Specify the SMS template ID and target recipients, and the system will automatically send SMS based on the template content.

Platform Configuration

Before calling, you need to complete the following configurations in the EngageLab SMS console:

SMS Template Setup: Before calling the API, please go to the Template Management Page to customize and submit SMS templates. The template can only be used after it has been approved and you have obtained the template ID.

API Key Configuration: Go to the API Key Page to create an API Basic authentication key.

Call Process

Please refer to the following process to call the API for sending SMS. If you have any questions, please contact customer service.

Call URL

POST https://smsapi.engagelab.com/v1/messages

Call Authentication

Use HTTP Basic Authentication for verification. Add Authorization in the HTTP Header:

              
              Authorization: Basic ${base64_auth_string}

            

The generation algorithm for the above base64_auth_string is: base64(dev_key:dev_secret)

Request Format

Request Header

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

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."
        }
    }
}

            

Request Parameters

A request object is expressed in JSON format, so the request header must include Content-Type: application/json.

If you have customized variables when creating the template, pass values for them here. If not passed, the variable key will be sent directly, such as {{var1}}.

Explanation for params

For template content with customized variable fields, assign values through params. For example, if the template content is Hi {{name}}, welcome to EngageLab, you need to assign the parameter as params:{"name":"Bob"}.

Request Examples

1. Sending Custom Notification Content:

              
              {
    "to": "+8618701235678", 
    "template":{
      "id":"notification-template",
      "params": {       
        "order":"123456"
        }
    }
}

            

2. Sending Custom Marketing Content:

              
              {
    "to": "+8618701235678", 
    "template":{
      "id":"marketing-template",
      "params": {       
        "name":"EngageLab",
        "promotion":"30%"
        }
    }
}

            

Response

HTTP status code is 200, and the response body contains the following fields:

Success Example (Single Target)

              
              {
    "plan_id": "1972488990548348928",
    "total_count": 1,
    "accepted_count": 1,
    "message_id": "1972488990804201472"
}

            

Success Example (Multiple Targets)

              
              {
    "plan_id": "1972484198153367552",
    "total_count": 2,
    "accepted_count": 2
}

            

Success Example (Scheduled Task)

              
              {
    "plan_id": "1972492618659033088",
    "total_count": 1,
    "accepted_count": 1,
    "schedule_info": {
        "task_id": 1972492621368553472
    }
}

            

Error Example

              
              {
    "plan_id": "1972490061974913024",
    "total_count": 1,
    "accepted_count": 1,
    "message": "err xxxx",
    "code": 1
}

            

Sending Errors

HTTP status code is 200, and the response body contains the following fields:

              
              {
    "plan_id": "string",
    "total_count": 0,
    "accepted_count": 0,
    "message": "string",
    "code": 0
}

            

Error Codes