Lifecycle Status Callback Interface

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

Callback Method

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

Data Structure

1. Outer Structure (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object array
    }
  ]
}

            

2. ReportLifecycle Object

The structure of each element in the rows array is as follows:

3. Status Object

Status details object:

Note: The following fields are used for internal statistics and will not be called back to the customer:

• analysis - Internal statistical analysis field

4. StatusData Object

Basic data related to status:

Note: The following fields are sensitive information or internal fields, have been filtered, and will not be called back to the customer:

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

5. Billing Object

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

Note: The following fields are internal billing fields and will not be called back to the customer:

• cost10000 - Internal billing field (1/10000 unit)
• sender_cost10000 - Sender cost (1/10000 unit)

6. ErrorDetail Object

Error details (returned only when an error occurs):

7. KwaiExtra Object

Kwai customer-specific extension information (returned only in delivered status and for Kwai customers):

Message Status Description

Common message status values:

Callback Examples

Example 1: Message successfully delivered

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "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": "+6598765433",
      "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 info)

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456791",
      "to": "+6598765434",
      "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": "+6598765435",
      "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 when the value is empty or zero
   • Sensitive information and internal fields have been filtered or cleared before callback

2. Security

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

3. Reception Requirements

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

4. Retry Mechanism

   • Will automatically retry after a callback failure
   • The retry interval gradually increases
   • Data will be saved in Redis during the retry period

5. Timestamp Description

   • itime: Timestamp when the callback occurred, in seconds
   • msg_time: Timestamp when the message was created, in seconds
   • delivered_time: Kwai-specific field, delivered 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 are passed when sending, this field will not appear in the callback data

Error Code Reference

Common error code descriptions (for specific error codes, please refer to the error code documentation):

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

Changelog

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