> 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/chinese-simplified/api-wen-dang-liao-tian/biao-zhun-tao-can/websocket.md).

# WebSocket

\[ 基础 URL： `ws.ggwp.com`]

## **事件**

`服务：chat，版本：v1，动作：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：** 会话通道的唯一标识符。对于游戏内消息，这可以标识在单场比赛中展开的会话。在论坛或留言板上，这可以代表一个独立的主题或讨论。如果你的平台包含多种通道类型（例如：大厅、对局、私信等），我们建议你在 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 两字母语言代码（例如：  `"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（字符串）- 消息被发送到的通信空间。例如：dm、party、guild、local
  * participants（数组\<string>）- 参与该通道的 user\_id
  * map（字符串）- 消息来源的世界、关卡或环境的标识符或名称
  * map\_version（字符串）- 地图的版本标识符，用于跟踪布局等变化
  * zone（字符串）- 地图内的子区域或命名区域，用于更细粒度的位置上下文
  * coordinates（对象）- 地图或区域中的空间位置
    * x（浮点数）- X 轴上的位置
    * y（浮点数）- Y 轴上的位置
    * z（浮点数）- 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": "fucking retards everywhere", 
		"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": "fucking retards everywhere", 
		"user_id": "user989", 
		"username": "nlxdz", 
		"timestamp": "2022-06-02 16:49:02", 
		"request_index": "1"
	}
}'
```

## **响应**

* 成功时

包含以下字段的字典：

* **message\_details**：与 payload 中传入的消息相关的详细信息
  * message\_details.message\_id：分配给该消息的唯一标识符。
  * message\_details.original\_message：用户发送的原始消息。
  * message\_details.flag：指示该消息是否被标记。
  * message\_details.severity：毒性严重程度（none、low、medium、high）。
  * 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：用户当前的审核状态（例如：active、muted）。
  * player\_details.user\_status.status：应用的具体审核动作（muted 等）。
  * player\_details.user\_status.expiry\_at：该审核动作到期的时间。
* **conversation\_summary**：包含与以下内容相关的详细信息的字典 `session_id` 的 payload
  * 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": "fucking retards everywhere",
		"flag": true,
		"severity": "high",
		"filtered_message": "***** ***** everywhere",
		"replaced_message": "It's gonna be legen..wait for it..dary..",
		"recommended_message": "",
		"language": "english",
		"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": {
			"high": 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": {
			"high": 1
		}
	},
	"recommendations": {
		"user989": [
			{
				"action": "session-mute",
				"trigger_message": "fucking retards everywhere",
				"trigger_time": "2022-06-02 16:49:02.000000",
				"duration": 3600
			}
		]
	},
	"request_index": "1"
}
```

* 无效载荷时

```json
无效输入键：<INPUT KEY>。请参考文档
```

* 无效路由时（无效的 `服务`, `版本`，和/或 `动作`)

```json
{'success': False, 'msg': '无效的动作'}
```

* 400
  * 无效或格式错误的请求。可能的原因：
    * &#x20;无效的 JSON 请求体输入
    * &#x20;无效的头部，包括超过 5KB 或包含不允许键的元数据
    * &#x20;缺少必填字段： `user_id`, `session_id`,  `message`
    * &#x20;无效的输入格式：无效的时间戳格式、超过消息字符限制等。&#x20;
* 403
  * 在 WebSocket 连接时
    * 无效或缺失的 API 密钥
    * 无效 `x-api-config`
* 500
  * 内部服务器错误