Custom Messages Send

If you have created custom template content on the OTP platform, use this API to send custom message content.

API Endpoint

POST https://otp.api.engagelab.cc/v1/custom-messages

Authentication

HTTP Basic Authentication is used for verification. Add the Authorization header in the HTTP request:

              
              Authorization: Basic ${base64_auth_string}

            

The base64_auth_string is generated using the following algorithm: base64(dev_key:dev_secret)

Request Format

Request Headers

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

            

Request Body

              
              {
    "to": "+8618701235678", 
    "template":{
      "id":"test-template-1",
      "params": {
        "code": "codevalue",
        "var1":"value1"
        }
    }
}

            

Request Parameters

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

Notes on params:

For template preset variables such as {{brand_name}}, {{ttl}}, and {{pwa_url}}, no values need to be passed—the system will automatically replace them with the content specified during template creation.

If the template type is a verification code, the {{code}} variable must be passed; otherwise, an error will occur.

For custom variables defined in the template content, assign values via params. For example, if the template content is Hi {{name}}, your verify code is {{code}}, the parameter params:{"name":"Bob"} should be passed.

Request Examples

1. Sending a custom verification code:

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

            

2. Sending a custom notification:

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

            

3. Sending custom marketing content:

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

            

Response Parameters

Successful Response

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

Note: The returned **send_channel** value does not represent the final delivery channel to the user, only the channel used at the current stage. For example, if the template strategy is configured to fall back to SMS after WhatsApp delivery fails, the API will initially return whatsapp. If delivery fails, the system will automatically switch to SMS.

Failed Response

http 状态码为 4xx 或者 5xx，响应体包含字段如下：

              
              {
    "code": 5001,
    "message": "sms send fail"
}