生命週期狀態回調

本文件描述了訊息生命週期狀態回調介面的資料結構和欄位說明。系統會在訊息狀態發生變化時，透過 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": "+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 } } ] }

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

此代碼塊在浮窗中顯示

範例 2：訊息發送失敗

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

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

此代碼塊在浮窗中顯示

範例 3：訊息送達失敗（帶計費資訊）

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

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

此代碼塊在浮窗中顯示

範例 4：快手客戶語音訊息送達

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

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

此代碼塊在浮窗中顯示

注意事項

欄位返回規則
- 所有標記為 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 欄位支援快手客戶
過濾敏感資訊欄位，增強安全性