OTP Send

Last updated:2024-03-08

Endpoint

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

Authentication

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

Authorization: Basic ${base64_auth_string}
          Authorization: Basic ${base64_auth_string}

        
This code block in the floating window

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

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": "+8618701235678", "template":{ "id":"test-template-1", "language": "default", "params": { "key1": "value1", "key2": "value2" } } }
          {
    "to": "+8618701235678",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

        
This code block in the floating window

Request Parameters

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

Parameter Type Option Description
to String Required The target, either a phone number or email address, e.g., +8613800138000, support@engagelab.com
template JSON Object Required Template information, including the sub-parameters below
|_ id String Required Template ID
|_ language String Optional Template language, defaults to 'default' if not provided
|_ params JSON Object Optional Custom template variable values. If you've customized variables when creating the template, pass their values here. If not provided, variable keys will be sent as is, e.g., {{var}}

Notes on params

  1. For templates with pre-set fields like from_id, if the param_vars field value is not passed, the message will use the template's pre-set from_id during dispatch;
  2. If param_vars field values are passed, such as param_vars:{"from_id":"12345"}, then during dispatch, the template's from_id will be replaced with 12345;
  3. Similarly, for custom variable fields in the template content created, assign values through param_vars, e.g., for template content Hi {{name}}, your verify code is {{code}}, assign parameters with param_vars:{"name":"Bob"}

Response Parameters

Success Response

Field Type Option Description
message_id String Required Message ID, uniquely identifies a message
send_channel String Required Indicates the current delivery channel, options include whatsapp/sms/email/voice
{ "message_id": "1725407449772531712", "send_channel": "sms" }
          {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

        
This code block in the floating window

Note, the returned send_channel value does not represent the final delivery channel to the user, but only the current phase's channel. For example, if the template's strategy is configured to fallback from WhatsApp to SMS upon delivery failure, the API return will initially show whatsapp, and later, if delivery failure is detected, the system will use the SMS channel for sending.

Failure Response

HTTP status code of 4xx or 5xx, response body includes the following fields:

Field Type Option Description
code int Required Error code, see Error Codes for details
message String Required Error details
{ "code": 5001, "message": "sms send fail" }
          {
    "code": 5001,
    "message": "sms send fail"
}

        
This code block in the floating window

Error Codes

Error Code HTTP Code Description
1000 500 Internal error
2001 401 Authentication failed, incorrect or missing token
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 JSON parameter format
3002 400 Incorrect request parameters, please verify against requirements
3003 400 Incorrect request parameters, business validation failed, refer to message field for error description
3004 400 Exceeded frequency limit, cannot resend to the same template and target user within the OTP validity period
4001 400 Related resource does not exist, e.g., using a non-existent template for message dispatch
5001 400 Verification message dispatch failed, refer to message field for error description
在文档中心打开
Contact Sales