ライフサイクルコールバック

このドキュメントは、メッセージライフサイクル状態コールバックインターフェースのデータ構造とフィールドの説明について記述しています。システムは、メッセージ状態が変更された際に、顧客が設定したURLにHTTP POSTを使用して状態情報を送信します。

コールバック方法

リクエスト方法: 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	Kwai専用拡張情報(以下参照)	いいえ

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

~~analysis~~ - 内部統計分析フィールド

4. StatusDataオブジェクト

状態に関連する基本データ:

フィールド名	型	説明	必須
`msg_time`	int64	メッセージ作成タイムスタンプ(秒単位)	はい
`message_id`	string	メッセージID	はい
`current_send_channel`	string	現在の送信チャネル名	はい
`template_key`	string	テンプレート設定キー	はい
`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オブジェクト

Kwai専用拡張情報(配信状態およびKwai顧客の場合のみ返されます):

フィールド名	型	説明	必須
`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": "無効な電話番号", "channel_code": "INVALID_NUMBER", "channel_message": "電話番号の形式が無効です" } } } ] }

              
              {
  "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": "無効な電話番号",
          "channel_code": "INVALID_NUMBER",
          "channel_message": "電話番号の形式が無効です"
        }
      }
    }
  ]
}

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

例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": "電話番号に到達できません", "channel_code": "UNREACHABLE", "channel_message": "加入者が不在です" } } } ] }

              
              {
  "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": "電話番号に到達できません",
          "channel_code": "UNREACHABLE",
          "channel_message": "加入者が不在です"
        }
      }
    }
  ]
}

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

例4: Kwai顧客の音声メッセージが配信された場合

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

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

一般的なエラーコードの説明(特定のエラーコードについてはエラーコードドキュメントを参照してください):

エラーコード	説明
0	エラーなし、操作成功
4001	無効な電話番号形式
4002	電話番号が存在しない
5001	チャネルによる拒否
5002	ユーザーに到達できない
6001	ネットワークタイムアウト

詳細なエラーコードの説明については、別途エラーコードドキュメントを参照してください。

変更履歴

2024-01: 初版
Kwai顧客向けのkwai_extraフィールドのサポートを追加
機密情報フィールドをフィルタリングしてセキュリティを強化