Template&Sender ID

This document describes the RESTful API interfaces related to template configuration and signature configuration.

Basic Information

• Domain: https://smsapi.engagelab.com
• Authentication Method: Basic Authentication (Base64 encoding)
  • Format: Authorization: Basic base64(apikey:apisecret)
  • Example: Encode apikey:apisecret in Base64, then add Authorization: Basic <encoded string> to the request header.
• Content-Type: application/json

Response Format

Successful Response

Successful responses directly return a data object or array:

              
              {
  "template_id": "123456789",
  "template_name": "Example Template",
  ...
}

            

Or a list response:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Example Template",
    ...
  }
]

            

Error Response

Error response format:

              
              {
  "code": 400,
  "message": "Error description"
}

            

Template Configuration Interfaces

1. Get Template Configuration List

Interface Description: Retrieve the list of all template configurations under the current business.

Request Information:

• Method: GET
• Path: /v1/template-configs
• Authentication: Required

Request Parameters: None

Response Example:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Order Notification Template",
    "template_type": "utility",
    "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "Company Name",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Response Field Description:

2. Get Template Configuration Details

Interface Description: Retrieve detailed information of a template configuration by template ID.

Request Information:

• Method: GET
• Path: /v1/template-configs/:templateId
• Authentication: Required

Path Parameters:

Response Example:

              
              {
  "template_id": "123456789",
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "Company Name",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Error Responses:

• 400: Template ID format error or template does not exist
• 500: Internal server error

3. Create Template Configuration

Interface Description: Create a new template configuration.

Request Information:

• Method: POST
• Path: /v1/template-configs
• Authentication: Required

Request Body:

              
              {
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

            

Request Field Description:

Response Example:

              
              {
  "template_id": "123456789"
}

            

Response Field Description:

Error Responses:

• 400: Parameter format error, parameter validation failed, signature configuration does not exist, signature status not approved
• 500: Internal server error

Business Rules:

• Templates are in "Pending Review" status (status=1) after creation.
• If a signature is added, the signature must be in an approved status.

4. Update Template Configuration

Interface Description: Update an existing template configuration.

Request Information:

• Method: PUT
• Path: /v1/template-configs/:templateId
• Authentication: Required

Path Parameters:

Request Body: Same as the creation interface, all fields are required.

Response Example:

              
              {
  "code": 0,
  "message": "success"
}

            

Error Responses:

• 400: Parameter format error, template does not exist, template in pending review status cannot be updated, plans in pending or running status cannot be updated, signature configuration does not exist, signature status not approved
• 500: Internal server error

Business Rules:

• Templates in pending review status cannot be updated.
• If there are pending or running message plans using the template, it cannot be updated.
• After updating, the template status will revert to "Pending Review" (status=1).

5. Delete Template Configuration

Interface Description: Delete a specified template configuration.

Request Information:

• Method: DELETE
• Path: /v1/template-configs/:templateId
• Authentication: Required

Path Parameters:

Response Example:

              
              {
  "code": 0,
  "message": "success"
}

            

Error Responses:

• 400: Template ID format error, template does not exist, plans in pending or running status cannot be deleted
• 500: Internal server error

Business Rules:

• If there are pending or running message plans using the template, it cannot be deleted.

Signature Configuration Interface

1. Get Signature Configuration List

Interface Description: Retrieve the list of all signature configurations under the current business.

Request Information:

• Method: GET
• Path: /v1/sign-configs
• Authentication: Required

Request Parameters: None

Response Example:

              
              [
  {
    "sign_id": "987654321",
    "sign_name": "Company Name",
    "status": 2,
    "related_template_count": 5,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

Response Field Description:

2. Get Signature Configuration Details

Interface Description: Retrieve detailed information of a signature configuration by signature ID.

Request Information:

• Method: GET
• Path: /v1/sign-configs/:signId
• Authentication: Required

Path Parameters:

Response Example:

              
              {
  "sign_id": "987654321",
  "sign_name": "Company Name",
  "status": 2,
  "related_template_count": 5,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

Error Responses:

• 400: Invalid signature ID format, signature does not exist, or signature does not belong to the current business.
• 500: Internal server error.

3. Create Signature Configuration

Interface Description: Create a new signature configuration.

Request Information:

• Method: POST
• Path: /v1/sign-configs
• Authentication: Required

Request Body:

              
              {
  "sign_name": "Company Name"
}

            

Request Field Description:

Response Example:

              
              {
  "sign_id": "987654321"
}

            

Response Field Description:

Error Responses:

• 400: Parameter format error, parameter validation failed, or signature name already exists.
• 500: Internal server error.

Business Rules:

• The status of the signature after creation is "Pending Review" (status=1).
• Signature names cannot be duplicated within the same business.

4. Update Signature Configuration

Interface Description: Update an existing signature configuration.

Request Information:

• Method: PUT
• Path: /v1/sign-configs/:signId
• Authentication: Required

Path Parameters:

Request Body: Same as the create interface.

Response Example:

              
              {
  "code": 0,
  "message": "success"
}

            

Error Responses:

• 400: Parameter format error, signature does not exist, signature does not belong to the current business, signature status is pending review and cannot be updated, signature name already exists, or there are pending or running plans that prevent updating.
• 500: Internal server error.

Business Rules:

• Signatures in pending review status cannot be updated.
• If there are pending or running message plans using the signature, it cannot be updated.
• After updating, the signature status will revert to "Pending Review" (status=1).

5. Delete Signature Configuration

Interface Description: Delete a specified signature configuration.

Request Information:

• Method: DELETE
• Path: /v1/sign-configs/:signId
• Authentication: Required

Path Parameters:

Response Example:

              
              {
  "code": 0,
  "message": "success"
}

            

Error Responses:

• 400: Invalid signature ID format, signature does not exist, signature does not belong to the current business, or there are pending or running plans that prevent deletion.
• 500: Internal server error.

Business Rules:

• If there are pending or running message plans using the signature, it cannot be deleted.

Status Code Description

Template Configuration Status (status)

Signature Configuration Status (status)

Signature Position (sign_position)

Template Type (template_type)

Error Code Description

Common Error Messages:

• invalid templateId: Invalid template ID format.
• template config not exist: Template configuration does not exist.
• invalid signId: Invalid signature ID format.
• sign config not exist: Signature configuration does not exist.
• sign_name already exist: Signature name already exists.
• can not update pending status template: Templates in pending review status cannot be updated.
• can not update pending status sign: Signatures in pending review status cannot be updated.
• there are pending or running plans using current template, can not update: There are pending or running plans using the template, cannot update.
• there are pending or running plans using current sign, can not update: There are pending or running plans using the signature, cannot update.
• sign status is not approved, can not use: Signature status is not approved, cannot be used.

Notes

1. All interfaces require authentication middleware validation.
2. All interfaces will automatically associate the authenticated user's business ID (businessId).
3. The creation and update operations of templates and signatures will trigger the review process.
4. If a template or signature is used by a message plan, it cannot be updated or deleted while the plan is in pending or running status.
5. Template content cannot contain prohibited characters: 【, 】, 、, 测试, test, [, ].
6. Signature names cannot contain prohibited characters: 【, 】, [, ].
7. The IDs of templates and signatures are numeric strings.