> 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/liao-tian-api-pi-liang.md).

# 聊天 API：批量

\[ 基础 URL: `api.ggwp.com`]

`POST` /chat/v2/batch

## **描述**

此 API 端点将处理一个输入消息数组，每条消息都带有其对应的会话 ID 和用户 ID，以及一组可配置的毒性过滤强度选项，并返回 4 个层级的信息：

* **消息详情** - 指示每条输入消息中毒性内容的存在情况和严重程度，以及移除毒性的消息的不同变体。
* **玩家详情** - 用于描述该特定用户在对话到该时刻为止的行为的属性。这包括已检测到的历史事件类型列表、玩家情绪、声誉分数和当前状态。
* **对话摘要** - 解释每个会话先前活动的指标。这些包括会话持续时间、消息和参与者数量、对话情绪以及检测到的事件总数，还有事件类型和严重程度。
* **建议** - 关于因该特定用户的历史或最近一系列有毒行为而施加的惩罚的信息。这包括惩罚本身、触发消息和时间，以及惩罚持续时间。该 `recommended_message` 字段在惩罚生效期间将返回空字符串。API 输出的这部分将提供以下惩罚：
  * 会话禁言：用户将在本场会话/比赛剩余时间内被禁言。 
  * 禁言：用户将在特定时长内在所有会话/比赛中被禁言。

## **请求头**

请参阅 `请求头` 上方部分，了解 `/chat/v2/message` 端点

## **参数**

`请求体`: 字典数组，每个字典包含以下字段：\
(*需要使用 utf-8 编码)*

* **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` 下。
* （可选） **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
      }
    }
  }
  ```

  注：还可以支持其他元数据键。请与客户代表合作，定义适用于你平台的具体键。

💡 **API 限制：此 API 施加以下限制，以较小者为准：**

* 200 条消息（数组中的项）
* 1 MB 请求体负载

如果超过这些限制中的任意一个，将返回 400 错误。

示例：

```json
[
	{
	  "session_id": "match_7765",
	  "message": "到处都是他妈的弱智",
	  "user_id": "user989",
	  "username": "nlxdz",
	  "timestamp": "2022-06-02 16:49:02"
	},
	{
	  "session_id": "lobby_4953",
	  "message": "嗨，朋友们！",
	  "user_id": "user159",
	  "username": "jrd",
	  "timestamp": "2022-06-02 16:49:35"
	}
]
```

示例调用：

```bash
curl --request POST 'https://api.ggwp.com/chat/v2/batch' \
--header 'x-api-key: api_key' \
--header 'Content-Type: application/json' \
--data-raw '[
	{
	  "session_id": "match_7765",
	  "message": "到处都是他妈的弱智",
	  "user_id": "user989",
	  "username": "nlxdz",
	  "timestamp": "2022-06-02 16:49:02"
	},
	{
	  "session_id": "lobby_4953",
	  "message": "嗨，朋友们！",
	  "user_id": "user159",
	  "username": "jrd",
	  "timestamp": "2022-06-02 16:49:35"
	}
]'
```

## **输出**

* 200 响应 - 操作成功

包含以下字段的字典：

* **message\_details**: 与负载中传入的每条消息相关的字典列表
  * message\_details\[n].message\_id: 分配给该消息的唯一标识符。
  * message\_details\[n].original\_message: 用户发送的原始消息。
  * message\_details\[n].flag: 指示该消息是否被标记。
  * message\_details\[n].severity: 毒性严重程度（无、低、中、高）。
  * message\_details\[n].filtered\_message: 已过滤标记词语的消息版本。&#x20;
    * 对于以空格分隔的语言（例如英语），会过滤整个单词。例如： `你是个混蛋` --> `你是个 *****`
    * 对于没有明确词边界的语言（例如韩语、日语、中文），只会过滤检测到的词本身。示例： `좆까고 있네`--> `*****고 있네`
  * message\_details\[n].replaced\_message: 用于替换原始消息的安全或幽默替代文本。
  * message\_details\[n].recommended\_message: 建议传递给客户端的消息版本。对于活跃用户，此值默认为 `filtered_message`。对于被禁言的用户， `recommended_message` 将为空字符串。
  * message\_details\[n].language: 检测到的消息语言。
  * message\_details\[n].violence: 如果消息包含暴力内容，则为 true。
  * message\_details\[n].verbal\_abuse: 如果消息包含言语辱骂，则为 true。
  * message\_details\[n].profanity: 如果消息包含脏话，则为 true。
  * message\_details\[n].sexual\_content: 如果消息包含性内容，则为 true。
  * message\_details\[n].identity\_hate: 如果消息包含身份仇恨，则为 true。
  * message\_details\[n].drugs: 如果消息包含毒品相关内容，则为 true。
  * message\_details\[n].self\_harm: 如果消息包含自残内容，则为 true。
  * message\_details\[n].custom: 如果消息包含自定义黑名单词条，则为 true。
  * message\_details\[n].spam: 如果消息包含垃圾信息，则为 true。
  * message\_details\[n].link: 如果消息包含外部链接，则为 true。
  * message\_details\[n].pii: 如果消息包含个人可识别信息，则为 true。
* **player\_details**: 包含与负载中每个 `user_id` 相关详细信息的字典
  * player\_details.\<user\_id>.\<session\_id>.user\_id: 用户的唯一标识符。
  * player\_details.\<user\_id>.\<session\_id>.username: 用户的显示名称。
  * player\_details.\<user\_id>.\<session\_id>.num\_messages: 发送的消息总数。
  * player\_details.\<user\_id>.\<session\_id>.num\_incidents: 事件数量。
  * player\_details.\<user\_id>.\<session\_id>.cumulative\_mood: 用户消息的整体情绪。
  * player\_details.\<user\_id>.\<session\_id>.min\_mood: 在用户消息中观察到的最低情绪值。
  * player\_details.\<user\_id>.\<session\_id>.max\_mood: 在用户消息中观察到的最高情绪值。
  * player\_details.\<user\_id>.\<session\_id>.incident\_types\_detected: 与该用户相关的事件类型列表。
  * player\_details.\<user\_id>.\<session\_id>.incidents\_by\_severity: 按严重程度分组的事件细分。
  * player\_details.\<user\_id>.\<session\_id>.reputation\_score: 根据行为历史得出的整体用户声誉分数。
  * player\_details.\<user\_id>.\<session\_id>.languages: 从用户消息中检测到的语言。
  * player\_details.\<user\_id>.\<session\_id>.user\_status: 用户当前的审核状态（例如：活跃、已禁言）。
  * player\_details.\<user\_id>.\<session\_id>.user\_status.status: 应用的具体审核操作（已禁言等）。
  * player\_details.\<user\_id>.\<session\_id>.user\_status.expiry\_at: 审核操作到期时间。
* **conversation\_summary**: 包含与负载中每个 `session_id` 相关详细信息的字典
  * conversation\_summary.\<session\_id>.start\_time: 对话会话开始时的时间戳。
  * conversation\_summary.\<session\_id>.session\_duration: 对话总时长（秒）。
  * conversation\_summary.\<session\_id>.num\_messages: 对话中的消息总数。
  * conversation\_summary.\<session\_id>.num\_participants: 对话中的用户数量。
  * conversation\_summary.\<session\_id>.num\_incidents: 事件总数。
  * conversation\_summary.\<session\_id>.conversation\_mood: 整个对话的整体情绪。
  * conversation\_summary.\<session\_id>.incident\_types\_detected: 在整个对话中发现的事件类型列表。
  * conversation\_summary.\<session\_id>.incidents\_by\_severity: 按严重程度分组的事件细分。
* **recommendations**: 包含针对每个 `user_id`
  * recommendations.\<user\_id>.\<session\_id>.action: 建议的审核操作（例如：禁言）。
  * recommendations.\<user\_id>.\<session\_id>.trigger\_message: 触发该建议的违规消息。
  * recommendations.\<user\_id>.\<session\_id>.trigger\_time: 触发消息的时间戳。
  * recommendations.\<user\_id>.\<session\_id>.duration: 操作应保持生效的时长（秒）。

示例输出：

```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": true,
            "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
        },
        {
            "message_id": "20220602164935.788776-92756195-c059-4e11-81a6-7faef57bd5bc",
            "original_message": "嗨，朋友们！",
            "flag": false,
            "severity": "无",
            "filtered_message": "嗨，朋友们！",
            "replaced_message": "我刚认识你们，但我已经爱上你们了",
            "recommended_message": "嗨，朋友们！",
            "language": "英语",
            "violence": false,
            "verbal_abuse": false,
            "profanity": false,
            "sexual_content": false,
            "identity_hate": false,
            "drugs": false,
            "self_harm": false,
            "custom": false,
            "spam": false,
            "link": false,
            "pii": false,
            "solicitation": false,
	    "scam": false
        }
    ],
    "player_details": {
        "user989": {
            "match_7765": {
                "user_id": "user989",
                "username": "nlxdz",
                "num_messages": 11,
                "num_incidents": 6,
                "cumulative_mood": 0.748,
                "min_mood": 0.0,
                "max_mood": 0.8615,
                "incident_types_detected": [
                    "言语辱骂",
                    "脏话",
                    "身份仇恨语言"
                ],
                "incidents_by_severity": {
                    "high": 2,
                    "medium": 3,
                    "low": 1
                },
                "reputation_score": 245,
                "languages": [
                    "english"
                ],
                "user_status": {
                    "status": "已禁言",
                    "expiry_at": "2022-06-03 16:49:02"
                }
            }
        },
        "user159": {
            "lobby_4953": {
                "user_id": "user159",
                "username": "jrd",
                "num_messages": 3,
                "num_incidents": 0,
                "cumulative_mood": 0.891,
                "min_mood": 0.5,
                "max_mood": 0.891,
                "incident_types_detected": [],
                "incidents_by_severity": {
                    "high": 0,
                    "medium": 0,
                    "low": 0
                },
                "reputation_score": 745,
                "languages": [
                    "english"
                ],
                "user_status": {
                    "status": "活跃"
                }
            }
        }
    },
    "conversation_summary": {
        "match_7765": {
            "start_time": "2022-05-27 16:53:03",
            "session_duration": 59,
            "num_messages": 46,
            "num_participants": 3,
            "num_incidents": 16,
            "conversation_mood": 0.9816,
            "incident_types_detected": [
                "言语辱骂",
                "脏话",
                "身份仇恨语言",
                "性骚扰"
            ],
            "incidents_by_severity": {
                "high": 4,
                "medium": 6,
                "low": 6
            }
        },
        "lobby_4953": {
            "start_time": "2022-06-02 15:25:01",
            "session_duration": 125,
            "num_messages": 33,
            "num_participants": 5,
            "num_incidents": 4,
            "conversation_mood": 0.9577,
            "incident_types_detected": [
                "身份偏见",
                "脏话",
                "毒品相关内容"
            ],
            "incidents_by_severity": {
                "high": 0,
                "medium": 1,
                "low": 3
            }
        }
    },
    "recommendations": {
        "user989": {
            "match_7765": [
                {
                    "action": "禁言",
                    "trigger_message": "愚蠢的混蛋死基佬",
                    "trigger_time": "2022-06-02 16:49:00",
                    "duration": 86400
                }
            ]
        }
    }
}
```

* 400
  * 无效的 JSON 输入、缺少必需字段、超过消息字符限制、超过 API 限制等。
* 403
  * API 密钥无效或缺失