Send OTP

This interface is used to generate a verification code by the EngageLab platform and send it according to the channel strategy specified in the template.

If you prefer to generate the verification code yourself instead of having the EngageLab platform generate it, you can call the EngageLab OTP Custom Send OTP interface.

Request URL

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

Authentication

Please refer to Authentication to learn how to perform API authentication.

Request Example

Request Header

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

            

Request Body

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

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 fields preset in the template such as from_id, if the params field value is not passed, the preset from_id of the template will be used when the message is sent;
2. If a params field value is passed, such as params:{"from_id":"12345"}, the template's from_id will be replaced with 12345 when the message is sent;
3. At the same time, for custom variable fields in the template content when creating the template, they are also assigned values through params. For example, if the template content is Hi {{name}}, your verify code is {{code}}, you need to assign the parameter params:{"name":"Bob"}.
4. Email Channel Special Variables: For the Email channel, you can dynamically override the email subject (subject), sender name (from_name), sender email (from_mail), etc., through params. For detailed advanced usage, please refer to Create Template - Email Template Variables Advanced Usage.

Response Parameters

Success Response

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

            

Note that the returned send_channel value does not represent the final channel delivered to the user, but only represents the channel used at this stage; for example, if the strategy configured in the template specifies that the WhatsApp channel fails to deliver and then automatically falls back to the SMS channel, the interface will return the whatsapp value. After sensing the delivery failure after a certain period of time, the system will use the SMS channel to send.

Failure 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

The table below only describes errors returned by this API during authentication, pre-send validation, and synchronous submission. Asynchronous delivery failures after a provider accepts the message are not returned by this API; obtain them via message status queries or callbacks.

Callers should use code to determine the error type. Use message to display the specific reason or for troubleshooting; do not rely on fixed message text for business logic.

Rate limit and send volume error notes

• 3004 is template OTP send rate control; the limit window is based on template configuration and may not equal the OTP validity period.
• 6001 and 6002 are security rate controls at the phone number or end-user IP dimension.
• 6003 and 6008 indicate this request hit a send volume limit; after the limit is reached and the service enters a suspended state, subsequent requests may return 6007.
• When you receive HTTP 429, do not retry immediately in a loop; retry later, and contact an administrator or technical support if it persists.
• 5011 through 5019 only cover failures identifiable during synchronous submission. Statuses such as empty numbers, powered-off phones, or carrier rejections that occur after a provider accepts the message may still be returned via asynchronous message status or callbacks.