> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/jp/apidokyumento-chat/pakkji/websocket.md).

# WebSocket

\[ ベースURL: `ws.ggwp.com`]

## **イベント**

`service: chat, version: v1, action: message`

## **説明**

GGWP Chat API には、開発者がアプリケーションにほぼリアルタイムのチャットフィルタリングと制裁機能を組み込める WebSocket エンドポイントが含まれています。この WebSocket エンドポイントは、上記で詳述した RESTful API と同じ機能出力をサポートします。

## **ヘッダー**

参照してください `ヘッダー` 上記のセクションを `/chat/v2/message` エンドポイント。この WebSocket エンドポイントは同じ `x-api-config` 上記のヘッダーを使用してチャットフィルターを設定します。

## **プロトコル**

GGWP の WebSocket エンドポイントは、WebSocket Secure（`wss`）プロトコルのみをサポートします。

## **制約**

* WebSocket エンドポイントの最大接続時間は 2 時間に制限されています。これを過ぎると自動的に切断され、サービスを継続利用するには再接続が必要です。
* WebSocket エンドポイントの接続が 10 分間アイドル状態（つまりメッセージが送信されない状態）になると、自動的に切断され、再接続が必要になります。

## **パラメーター**

`payload`: 以下のフィールドを含む辞書:

* **session\_id:** 会話チャネルの一意の識別子。ゲームプレイメッセージの場合、1 つの試合内で展開される会話を識別できます。フォーラムや掲示板では、個別のスレッドや議論を表すことがあります。プラットフォームにさまざまなチャネルタイプ（例: lobby、match、direct message など）が含まれる場合は、会話タイプ別のさらなる分析を可能にするため、session\_id にこの情報を含めることを推奨します。推奨される形式は次のとおりです:

  ```json
    session_id = "channelType_numericID"
  ```
* **message:** 会話中にユーザーによって送信されたメッセージ。1,000 文字を超えることはできません。
* **user\_id:** メッセージを送信したプレイヤーまたはユーザーの一意の識別子。
* （任意） **username**: ユーザーが選んだ表示名を含む文字列。
* （任意） **timestamp:** メッセージが発生した時刻 *YYYY-MM-DD HH:MM:SS.SSS または YYYY-MM-DD HH:MM:SS* 形式、UTC。指定しない場合は、サーバー側の UTC タイムスタンプが代わりに追加されます。
* （任意） **language**: 処理対象メッセージの言語。省略した場合、API はメッセージ内容と過去のユーザー履歴から言語を検出しようとします。標準的な英語の言語名（例: `"english"` または `"spanish"`）、および ISO 639-1 の 2 文字言語コード（例:  `"en"` または `"es"`）。完全なロケールタグである `"en-US"`, `"en-GB"`, `"pt-BR"`、および `"es-MX"` は現在サポートされていません。代わりに `"en"`, `"pt"`、または `"es"` を送信してください。
* （任意） **message\_index**: 送信されたメッセージを追跡するための文字列フィールド。出力では `message_details` の下に含まれます。
* （任意） **request\_index:** 送信された非同期リクエストを追跡するための文字列フィールド。
* （任意） **message\_url**: メッセージに付与された URL を追跡するための文字列フィールド。有効なのは http または https スキームのみです。有効で指定した場合、ダッシュボードに表示されます。
* （任意） **metadata**: メッセージに関連付けられたメタデータを追跡するための辞書型フィールド。5KB 未満である必要があります。許可されたキーと対応する型のみ有効です。サポートされるキー:

  * channel (string) - メッセージが渡される通信スペース。例: dm、party、guild、local
  * participants (array\<string>) - チャンネルに参加している user\_id
  * map (string) - メッセージの発生元となるワールド、レベル、または環境の識別子または名前
  * map\_version (string) - マップのバージョン識別子。レイアウトなどの変更を追跡するために使用されます
  * zone (string) - より細かな位置コンテキストに使用される、マップ内のサブセクションまたは名前付き領域
  * coordinates (object) - マップまたはゾーン内の空間位置
    * x (float) - X 軸方向の位置
    * y (float) - Y 軸方向の位置
    * z (float) - Z 軸方向の位置

  例:

  ```json
  {
    "metadata": {
      "channel": "dm",
      "participants": ["user989", "user990"],
      "map":"golden_wasteland",
      "map_version":"2026.03.1",
      "zone":"cacti_forest",
      "coordinates":{
         "x":123.45,
         "y":67.89,
         "z":-10.25
      }
    }
  }
  ```

  注: 追加のメタデータキーにも対応できます。お客様担当者と協力して、プラットフォームに適用可能な具体的なキーを定義してください。

例

```json
{
	"service": "chat", 
	"version": "v1", 
	"action": "message", 
	"payload": {
		"session_id": "match_7765", 
		"message": "どこもかしこもクソ野郎ども", 
		"user_id": "user989", 
		"username": "nlxdz", 
		"timestamp": "2022-06-02 16:49:02", 
		"request_index": "1"
	}
}
```

サンプル呼び出し:

次の例では [wscat](https://www.npmjs.com/package/wscat) をアプリケーションクライアントとして使用して WebSocket エンドポイントに接続します:

```bash
wscat --header 'x-api-key: api_key' \\
--connect 'wss://ws.ggwp.com' \\
--execute '{
	"service": "chat", 
	"version": "v1", 
	"action": "message", 
	"payload": {
		"session_id": "match_7765", 
		"message": "どこもかしこもクソ野郎ども", 
		"user_id": "user989", 
		"username": "nlxdz", 
		"timestamp": "2022-06-02 16:49:02", 
		"request_index": "1"
	}
}'
```

## **応答**

* 成功時

以下のフィールドを含む辞書:

* **message\_details**: ペイロードで渡されたメッセージに関する詳細
  * message\_details.message\_id: メッセージに割り当てられた一意の識別子。
  * message\_details.original\_message: ユーザーが送信した生のメッセージ。
  * message\_details.flag: メッセージがフラグ付けされたかどうかを示します。
  * message\_details.severity: 毒性の深刻度（なし、低、中、高）。
  * message\_details.filtered\_message: フラグ対象の用語がフィルタリングされたメッセージのバージョン。&#x20;
    * スペース区切りの言語（例: 英語）では、単語全体がフィルタリングされます。例: `お前はクソ野郎だ` --> `お前は *****`
    * 明確な単語境界のない言語（例: 韓国語、日本語、中国語）では、検出された語そのものだけがフィルタリングされます。例: `좆까고 있네`--> `*****고 있네`
  * message\_details.replaced\_message: 元のメッセージを置き換えるために生成された、安全またはユーモラスな代替文。
  * message\_details.recommended\_message: クライアントに渡すことが推奨されるメッセージのバージョン。アクティブユーザーの場合、この値の既定値は `filtered_message`です。ミュートされたユーザーの場合、 `recommended_message` は空文字列になります。
  * message\_details.language: メッセージの検出言語。
  * message\_details.violence: メッセージに暴力が含まれる場合は true。
  * message\_details.verbal\_abuse: メッセージに暴言が含まれる場合は true。
  * message\_details.profanity: メッセージに冒とく語が含まれる場合は true。
  * message\_details.sexual\_content: メッセージに性的内容が含まれる場合は true。
  * message\_details.identity\_hate: メッセージに属性への憎悪が含まれる場合は true。
  * message\_details.drugs: メッセージに薬物への言及が含まれる場合は true。
  * message\_details.self\_harm: メッセージに自傷行為が含まれる場合は true。
  * message\_details.custom: メッセージにカスタムブロックリストの用語が含まれる場合は true。
  * message\_details.spam: メッセージにスパムが含まれる場合は true。
  * message\_details.link: メッセージに外部リンクが含まれる場合は true。
  * message\_details.pii: メッセージに個人を特定できる情報が含まれる場合は true。
* **player\_details**: 以下に関する詳細を含む辞書 `user_id` のペイロード内の `session_id`
  * player\_details.user\_id: ユーザーの一意の識別子。
  * player\_details.username: ユーザーの表示名。
  * player\_details.num\_messages: 送信されたメッセージの総数。
  * player\_details.num\_incidents: インシデント数。
  * player\_details.cumulative\_mood: ユーザーのメッセージ全体の感情傾向。
  * player\_details.min\_mood: ユーザーのメッセージで観測された最も低い感情傾向。
  * player\_details.max\_mood: ユーザーのメッセージで観測された最も高い感情傾向。
  * player\_details.incident\_types\_detected: ユーザーに関連付けられたインシデント種別の一覧。
  * player\_details.incidents\_by\_severity: 深刻度レベルごとにまとめたインシデントの内訳。
  * player\_details.reputation\_score: 行動履歴から算出されたユーザーの総合レピュテーションスコア。
  * player\_details.languages: ユーザーのメッセージから検出された言語。
  * player\_details.user\_status: ユーザーの現在のモデレーション状態（例: アクティブ、ミュート）。
  * player\_details.user\_status.status: 適用された具体的なモデレーション措置（ミュートなど）。
  * player\_details.user\_status.expiry\_at: モデレーション措置の有効期限が切れる時刻。
* **conversation\_summary**: 以下に関する詳細を含む辞書 `session_id` のペイロード
  * conversation\_summary.start\_time: 会話セッションが開始されたタイムスタンプ。
  * conversation\_summary.session\_duration: 会話の合計継続時間（秒単位）。
  * conversation\_summary.num\_messages: 会話内のメッセージ総数。
  * conversation\_summary.num\_participants: 会話内のユーザー数。
  * conversation\_summary.num\_incidents: インシデントの総数。
  * conversation\_summary.conversation\_mood: 会話全体の感情傾向。
  * conversation\_summary.incident\_types\_detected: 会話全体で見つかったインシデント種別の一覧。
  * conversation\_summary.incidents\_by\_severity: 深刻度レベルごとにまとめたインシデントの内訳。
* **recommendations**: 以下に対して実行する推奨アクションを含む辞書 `user_id`
  * recommendations.\<user\_id>.action: 推奨されるモデレーションアクション（例: ミュート）。
  * recommendations.\<user\_id>.trigger\_message: 推奨のきっかけとなった問題のあるメッセージ。
  * recommendations.\<user\_id>.trigger\_time: きっかけとなったメッセージのタイムスタンプ。
  * recommendations.\<user\_id>.duration: アクションを有効にしておく時間（秒）。
* **request\_index**: 送信された非同期リクエストを追跡するためのインデックス。

サンプル出力:

```json
{
	"message_details": {
		"message_id": "20220602164902.482311-946bb8a9-0766-4c31-995a-d910da8531e5",
		"original_message": "どこもかしこもクソ野郎ども",
		"flag": true,
		"severity": "高",
		"filtered_message": "***** ***** どこもかしこも",
		"replaced_message": "伝説になる…待てよ…伝説的だ…",
		"recommended_message": "",
		"language": "英語",
		"violence": false,
		"verbal_abuse": false,
		"profanity": true,
		"sexual_content": false,
		"identity_hate": true,
		"drugs": false,
		"self_harm": false,
		"custom": false,
		"spam": false,
		"link": false,
		"pii": false,
		"solicitation": false,
	    	"scam": false
	},
	"player_details": {
		"user_id": "user989",
		"username": "nlxdz",
		"num_messages": 1,
		"num_incidents": 1,
		"cumulative_mood": -0.8518,
		"min_mood": -0.8518,
		"max_mood": -0.8518,
		"incident_types_detected": [
			"identity_hate_language",
			"profanity",
			"identity_hate",
			"chat_verbal_abuse"
		],
		"incidents_by_severity": {
			"高": 1
		},
		"reputation_score": 450,
	        "languages": [
			"english"
		],
		"user_status": {
			"status": "session-muted",
			"expiry_at": "2022-06-02 17:49:02"
		}
	},
	"conversation_summary": {
		"start_time": "2022-06-02 16:49:02.000000",
		"session_duration": 0,
		"num_messages": 1,
		"num_participants": 1,
		"conversation_mood": -0.8518,
		"incident_types_detected": [
			"identity_hate_language",
			"profanity",
			"identity_hate",
			"chat_verbal_abuse"
		],
		"incidents_by_severity": {
			"高": 1
		}
	},
	"recommendations": {
		"user989": [
			{
				"action": "session-mute",
				"trigger_message": "どこもかしこもクソ野郎ども",
				"trigger_time": "2022-06-02 16:49:02.000000",
				"duration": 3600
			}
		]
	},
	"request_index": "1"
}
```

* 不正なペイロードの場合

```json
無効な入力キー: <INPUT KEY>。ドキュメントを参照してください
```

* 不正なルートの場合（無効な `service`, `version`、および/または `action`)

```json
{'success': False, 'msg': '無効なアクション'}
```

* 400
  * 無効または形式不正なリクエスト。考えられる原因:
    * &#x20;無効な JSON 本文入力
    * &#x20;5KB を超えるメタデータや、許可されていないキーを含む無効なヘッダー
    * &#x20;必須フィールドが不足しています: `user_id`, `session_id`,  `message`
    * &#x20;入力形式が無効: タイムスタンプ形式が無効、メッセージ文字数制限超過など。&#x20;
* 403
  * WebSocket 接続時
    * API キーが無効または不足しています
    * 無効 `x-api-config`
* 500
  * 内部サーバーエラー