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: Perform Base64 encoding on apikey:apisecret, then add Authorization: Basic <encoded string> to the request header.
• Content-Type: application/json

Response Format

Successful Response

Successful responses directly return data objects or arrays:

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

            

or list responses:

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

            

Error Response

Error response format:

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

            

Template Configuration Interface

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 about 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:

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

            

Error Responses:

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

Business Rules:

• The status of the template after creation is "Pending review" (status=1).
• 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 create interface, all fields are required.

Response Example:

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

            

Error Responses:

• 400: Parameter format error, template does not exist, template status is pending review and cannot be updated, there are pending or running plans that 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 the update, 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, there are pending or running plans that 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 API

1. Get Signature Configuration List

API 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

API 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

API 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:

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

            

Error Responses:

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

Business Rules:

• The status of a newly created signature is "Pending Review" (status=1).
• Signature names under the same business cannot be duplicated.

4. Update Signature Configuration

API 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 API.

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 cannot be updated.
• 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

API 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 cannot be deleted.
• 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 use.

Notes

1. All APIs require authentication middleware validation.
2. All APIs will automatically associate the authenticated user's business ID (businessId).
3. Creation and update operations for 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. Template and signature IDs are numeric strings.