Custom Messages Delivery

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

Endpoint

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

Authentication

Use HTTP Basic Authentication for authentication, and add Authorization to the HTTP header:

              
              Authorization: Basic ${base64_auth_string}

            

The generation algorithm for base64_auth_string is: 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

1. For preset template variables such as {{brand_name}}, {{ttl}}, and {{pwa_url}}, you do not need to pass them. The system automatically replaces them with the content specified when the template was created.
2. If the template type is a verification code, you must pass the {{code}} variable; otherwise, an error will be returned.
3. If the template content contains custom variable fields defined when the template was created, assign values to them through params as well. For example, for the template content Hi {{name}}, your verify code is {{code}}, you need to assign the parameter params: {"name":"Bob"}.

Request Examples

1. Send a custom verification code

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

            

2. Send custom notification content

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

            

3. Send 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 that the returned send_channel value does not represent the final channel used to deliver the message to the user. It only indicates the channel currently being used. For example, if the strategy configured in the template specifies that when WhatsApp delivery fails it should automatically retry through the SMS channel, the API response will return whatsapp. After delivery failure is detected after a certain period of time, the system will then send through the SMS channel.

Failed Response

The HTTP status code is 4xx or 5xx, and the response body contains the following fields:

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

            

Error Codes