Lifecycle 狀態回調接口

本文檔描述了消息生命周期狀態回調接口的數據結構和字段說明。系統會在消息狀態發生變化時，通過 HTTP POST 方式將狀態信息回調到客戶配置的 URL。

回調方式

請求方法: POST
Content-Type: application/json
成功響應: HTTP 200 或 204 狀態碼
失敗重試: 如果客戶未返回成功狀態碼，系統會自動進行重試

數據結構

1. 外層結構 (ReportLifecycles)

{ "total": 1, "rows": [ { // ReportLifecycle 對象數組 } ] }

              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle 對象數組
    }
  ]
}

此代碼塊在浮窗中顯示

字段名	類型	說明	是否必返
`total`	int64	總記錄數	是
`rows`	array	生命週期狀態數據數組	是

2. ReportLifecycle 對象

rows 數組中的每個元素結構如下：

字段名	類型	說明	是否必返
`message_id`	string	消息 ID	是
`to`	string	接收方號碼	是
`server`	string	服務類型	是
`channel`	string	渠道類型	是
`itime`	int64	回調時間戳(秒)	是
`custom_args`	map[string]any	自定義參數（發送時傳入的參數）	否
`status`	object	狀態詳情對象	否

3. Status 對象

狀態詳細信息對象：

字段名	類型	說明	是否必返
`message_status`	string	消息狀態，如: `sent`、`sent_fail`、`delivered`、`delivered_fail`、`verified` 等	是
`status_data`	object	狀態數據對象，詳見下方	是
`billing`	object	計費信息對象，詳見下方	否
`error_code`	int	錯誤碼，0 表示無錯誤	是
`error_detail`	object	錯誤詳情對象，詳見下方	否
`kwai_extra`	object	快手專用擴展信息，詳見下方	否

注意：以下字段為內部統計使用，不會回調給客戶：

~~analysis~~ - 內部統計分析字段

4. StatusData 對象

狀態相關的基礎數據：

字段名	類型	說明	是否必返
`msg_time`	int64	消息創建時間戳(秒)	是
`message_id`	string	消息 ID	是
`current_send_channel`	string	當前發送渠道名稱	是
`template_key`	string	模板配置 Key	是
`business_id`	string	業務 ID	是

注意：以下字段為敏感信息或內部字段，已被過濾，不會回調給客戶：

~~message_content~~ - 消息內容（敏感信息）
~~parts~~ - 消息分片數（內部字段）
~~msg_type~~ - 消息類型（內部字段）
~~protocol_type~~ - 協議類型（內部字段）
~~supplier_ids~~ - 供應商 ID（敏感信息）

5. Billing 對象

計費信息（僅在有計費數據時返回）：

字段名	類型	說明	是否必返
`cost`	float64	費用金額（保留 4 位小數）	是
`currency`	string	幣種，固定為 "USD"	是

注意：以下字段為內部計費字段，不會回調給客戶：

~~cost10000~~ - 內部計費字段（萬分之一單位）
~~sender_cost10000~~ - 發送方成本（萬分之一單位）

6. ErrorDetail 對象

錯誤詳情（僅在發生錯誤時返回）：

字段名	類型	說明	是否必返
`message`	string	錯誤消息描述	是
`channel_code`	string	渠道返回的原始錯誤碼	是
`channel_message`	string	渠道返回的原始錯誤消息	是

7. KwaiExtra 對象

快手客戶專用擴展信息（僅在送達狀態且為快手客戶時返回）：

字段名	類型	說明	是否必返
`delivered_time`	int64	送達時間戳(毫秒)	是
`parts`	int	計費條數	是
`duration`	int64	接聽時長(秒)，僅語音消息有此字段	否

消息狀態說明

常見的消息狀態值：

狀態值	說明
`sent`	已發送到渠道
`sent_fail`	發送失敗
`delivered`	已送達到用戶終端
`delivered_fail`	送達失敗
`verified`	用戶已驗證（如 OTP 驗證碼被使用）

回調示例

示例 1：消息成功送達

{ "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 } } ] }

              
              {
  "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
      }
    }
  ]
}

此代碼塊在浮窗中顯示

示例 2：消息發送失敗

{ "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" } } } ] }

              
              {
  "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"
        }
      }
    }
  ]
}

此代碼塊在浮窗中顯示

示例 3：消息送達失敗（帶計費信息）

{ "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" } } } ] }

              
              {
  "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"
        }
      }
    }
  ]
}

此代碼塊在浮窗中顯示

示例 4：快手客戶語音消息送達

{ "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 } } } ] }

              
              {
  "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
        }
      }
    }
  ]
}

此代碼塊在浮窗中顯示

注意事項

字段返回規則
- 所有標記為 omitempty 的字段，在值為空或零值時不會出現在返回的 JSON 中
- 敏感信息和內部字段已在回調前被過濾或清空
安全性
- 消息內容（message_content）不會回調給客戶
- 供應商 ID（supplier_ids）等敏感信息已被過濾
- 內部計費字段（cost10000、sender_cost10000）不會回調
接收要求
- 客戶的回調接口必須在5 秒內返回響應
- 必須返回 HTTP 200 或 204 狀態碼表示接收成功
- 如果返回其他狀態碼或超時，系統將進行自動重試
重試機制
- 回調失敗後會自動進行重試
- 重試間隔逐步增加
- 重試期間數據會保存在 Redis 中
時間戳說明
- itime：回調發生的時間戳，單位為秒
- msg_time：消息創建的時間戳，單位為秒
- delivered_time：快手專用字段，送達時間戳，單位為毫秒
自定義參數
- custom_args 字段會原樣返回發送消息時傳入的自定義參數
- 如果發送時未傳入自定義參數，此字段不會出現在回調數據中

錯誤碼參考

常見錯誤碼說明（具體錯誤碼請參考錯誤碼文檔）：

錯誤碼	說明
0	無錯誤，操作成功
4001	號碼格式錯誤
4002	號碼不存在
5001	渠道拒絕
5002	用戶不可達
6001	網絡超時

更詳細的錯誤碼說明請參考單獨的錯誤碼文檔。

更新日誌

2024-01: 初始版本
添加了 kwai_extra 字段支持快手客戶
過濾敏感信息字段，增強安全性