Lifesycle Callback

This document describes the data structure and field descriptions of the message lifecycle state callback interface. The system will use HTTP POST to send state information to the URL configured by the customer when the message state changes.

Callback Method

• Request Method: POST
• Content-Type: application/json
• Successful Response: HTTP 200 or 204 status code
• Failure Retry: If the customer does not return a successful status code, the system will automatically retry

Data Structure

1. Outer Structure (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // Array of ReportLifecycle objects
    }
  ]
}

            

2. ReportLifecycle Object

Each element in the rows array has the following structure:

3. Status Object

Detailed status information object:

Note: The following fields are for internal statistics and will not be included in the callback to the customer:

• analysis - Internal statistical analysis field

4. StatusData Object

Basic data related to the status:

Note: The following fields contain sensitive information or are internal fields and have been filtered out and will not be included in the callback to the customer:

• message_content - Message content (sensitive information)
• parts - Number of message parts (internal field)
• msg_type - Message type (internal field)
• protocol_type - Protocol type (internal field)
• supplier_ids - Supplier IDs (sensitive information)

5. Billing Object

Billing information (returned only when billing data is available):

Note: The following fields are internal billing fields and will not be included in the callback to the customer:

• cost10000 - Internal billing field (unit: ten-thousandth)
• sender_cost10000 - Sender cost (unit: ten-thousandth)

6. ErrorDetail Object

Error details (returned only when an error occurs):

7. KwaiExtra Object

Kwai-specific extended information (returned only for delivery status and Kwai customers):

Message Status Description

Common message status values:

Callback Examples

Example 1: Message Successfully Delivered

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+8613800138000",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}

            

Example 2: Message Sending Failed

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+8613800138001",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number",
          "channel_code": "INVALID_NUMBER",
          "channel_message": "The phone number format is invalid"
        }
      }
    }
  ]
}

            

Example 3: Message Delivery Failed (with Billing Information)

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456791",
      "to": "+8613800138002",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234570,
      "custom_args": {
        "campaign": "new_year_promo"
      },
      "status": {
        "message_status": "delivered_fail",
        "status_data": {
          "msg_time": 1701234562,
          "message_id": "123456791",
          "current_send_channel": "CHANNEL_C",
          "template_key": "marketing",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.0045,
          "currency": "USD"
        },
        "error_code": 5002,
        "error_detail": {
          "message": "Phone number unreachable",
          "channel_code": "UNREACHABLE",
          "channel_message": "Subscriber absent"
        }
      }
    }
  ]
}

            

Example 4: Kwai Customer Voice Message Delivered

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456792",
      "to": "+8613800138003",
      "server": "voice",
      "channel": "voice",
      "itime": 1701234575,
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234565,
          "message_id": "123456792",
          "current_send_channel": "VOICE_CHANNEL_A",
          "template_key": "voice_verify",
          "business_id": "2001"
        },
        "billing": {
          "cost": 0.012,
          "currency": "USD"
        },
        "error_code": 0,
        "kwai_extra": {
          "delivered_time": 1701234575000,
          "parts": 1,
          "duration": 45
        }
      }
    }
  ]
}

            

Notes

1. Field Return Rules

   • All fields marked as omitempty will not appear in the returned JSON if their values are empty or zero.
   • Sensitive information and internal fields have been filtered or cleared before the callback.

2. Security

   • Message content (message_content) will not be included in the callback to the customer.
   • Sensitive information such as supplier IDs (supplier_ids) has been filtered.
   • Internal billing fields (cost10000, sender_cost10000) will not be included.

3. Receiving Requirements

   • The customer's callback interface must respond within 5 seconds.
   • Must return HTTP 200 or 204 status code to indicate successful receipt.
   • If other status codes are returned or a timeout occurs, the system will automatically retry.

4. Retry Mechanism

   • Automatic retries will be performed after a callback failure.
   • Retry intervals will gradually increase.
   • Data will be stored in Redis during the retry period.

5. Timestamp Description

   • itime: The timestamp of the callback occurrence, in seconds.
   • msg_time: The timestamp of message creation, in seconds.
   • delivered_time: Kwai-specific field, delivery timestamp, in milliseconds.

6. Custom Parameters

   • The custom_args field will return the custom parameters passed when sending the message as-is.
   • If no custom parameters were passed during sending, this field will not appear in the callback data.

Error Code Reference

Common error code descriptions (refer to the error code document for specific error codes):

For more detailed error code descriptions, please refer to the separate error code document.

Change Log

• 2024-01: Initial version
• Added support for the kwai_extra field for Kwai customers
• Filtered sensitive information fields to enhance security