ライフサイクルステータスコールバック

このドキュメントでは、メッセージのライフサイクルステータスコールバックインターフェースのデータ構造とフィールドの説明を記述します。メッセージのステータスが変化すると、システムは HTTP POST でお客様が設定した URL にステータス情報をコールバックします。

コールバック方式

リクエストメソッド: POST
Content-Type: application/json
成功レスポンス: HTTP 200 または 204 ステータスコード
失敗時のリトライ: お客様が成功ステータスコードを返さない場合、システムは自動的にリトライします

データ構造

1. 外側の構造（ReportLifecycles）

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

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

このコードブロックはフローティングウィンドウ内に表示されます

フィールド名	型	説明	必須
`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	Kwai 専用の拡張情報。下記参照	いいえ

注意: 以下のフィールドは内部統計用であり、お客様にはコールバックされません。

~~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~~ - 内部課金フィールド（1/10000 単位）
~~sender_cost10000~~ - 送信者コスト（1/10000 単位）

6. ErrorDetail オブジェクト

エラー詳細（エラー発生時のみ返却）:

フィールド名	型	説明	必須
`message`	string	エラーメッセージの説明	はい
`channel_code`	string	チャネルが返した元のエラーコード	はい
`channel_message`	string	チャネルが返した元のエラーメッセージ	はい

7. KwaiExtra オブジェクト

Kwai 顧客専用の拡張情報（delivered ステータスかつ Kwai 顧客の場合のみ返却）:

フィールド名	型	説明	必須
`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: Kwai 顧客の音声メッセージの配信

{ "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: Kwai 専用フィールド。配信タイムスタンプ。ミリ秒単位
カスタムパラメータ
- custom_args フィールドは、メッセージ送信時に渡したカスタムパラメータをそのまま返します
- 送信時にカスタムパラメータを渡さなかった場合、このフィールドはコールバックデータに含まれません

エラーコードリファレンス

一般的なエラーコードの説明（具体的なエラーコードはエラーコードのドキュメントを参照してください）:

エラーコード	説明
0	エラーなし。操作成功
4001	番号の形式エラー
4002	番号が存在しない
5001	チャネルが拒否
5002	ユーザーに到達不能
6001	ネットワークタイムアウト

より詳細なエラーコードの説明は、別途用意されたエラーコードのドキュメントを参照してください。

変更履歴

2024-01: 初版
Kwai 顧客に対応するため kwai_extra フィールドを追加
セキュリティ強化のため機密情報フィールドをフィルタリング