稽核記錄與違規

本頁的介面查詢和處理你的稽核記錄，查詢和清除使用者的違規，查詢統計，以及以使用者的名義舉報。這些介面與控制檯“內容安全”中的“稽核記錄”“平臺處置”“使用者違規”和“統計”相同，可以用來把稽核接入你自己的稽核系統或客服系統。稽核記錄的來源和處理規則見人工稽核，在控制檯中的操作見稽核記錄。

接入自己的稽核系統時，一般這樣做：

1. 訂閱回撥事件 moderation.item_created（有新的稽核記錄），或定期按 status=pending 查詢稽核記錄列表；
2. 讀取稽核記錄的內容，交給稽核人員判斷；
3. 作出結論，需要時同時撤回訊息、清除資料、禁言或封禁作者。

說明：

• 只能看到你的佇列：介面只返回你的稽核記錄（包括你轉交平臺的記錄的狀態），平臺規則命中、由平臺稽核的記錄不會出現。平臺對你的應用執行的處置用查詢平臺的處置檢視。
• 內容與列表分開：列表和單個記錄都不含使用者的內容，內容只能透過讀取稽核記錄的內容取得。透過介面讀取內容不寫操作日誌，請在你的系統中自行記錄誰看過哪些內容。
• 操作日誌：作出結論、轉交平臺和清除違規寫入操作日誌，操作人為呼叫所用的服務端金鑰；記錄中的結論顯示為“App 憑據”。
• 呼叫額度：批次作出結論按記錄數計入應用的 OpenAPI 呼叫額度，見批次介面。

查詢稽核記錄列表

分頁查詢稽核記錄，見分頁。預設只返回未結束的記錄（pending、auto_violation），按優先順序、再按建立時間從新到舊排列；order=oldest 時同一優先順序中從舊到新，處理積壓時使用。只查詢已結束的狀態時，不按優先順序，只按建立時間排列。

GET/{org_name}/{app_name}/moderation/items

路徑引數

org_name、app_name 見接入概述。

查詢引數

引數	型別	必填	說明
status	String	否	狀態，可以重複給出多個，如 status=violation&status=no_violation，取值見稽核記錄物件。預設為 pending 和 auto_violation
scene	String	否	場景，取值見稽核的內容和時機；舉報使用者、群、聊天室的記錄為 report
target_type	String	否	物件的型別，取值見稽核記錄物件
category	String	否	含有這個類別的記錄
source	String	否	含有這種來源的記錄：word_list 詞庫、provider 第三方稽核、report 舉報、url_rejected 地址無法稽核、escalation 轉交平臺
author	String	否	作者的使用者名稱。使用者不存在時返回空列表
priority	Number	否	優先順序，0 到 2
from、to	String	否	建立時間的範圍，RFC 3339 格式，如 2026-10-04T19:50:00Z
escalated	Boolean	否	為 true 時改為查詢你轉交平臺的記錄
order	String	否	為 oldest 時從舊到新排列
limit	Number	否	每頁的條數，預設 20，最大 100
cursor	String	否	上一頁返回的 next_cursor

請求示例

curl "$IM_API/$ORG/$APP/moderation/items?source=word_list&limit=20" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
items	Array<Object>	稽核記錄物件的陣列，不含 actions
next_cursor	String	下一頁的遊標，沒有下一頁時為 null

{
  "items": [
    {
      "item_id": "100319142342557696",
      "queue": "tenant",
      "status": "pending",
      "scene": "message",
      "target_type": "message",
      "target_id": "100319140375429120",
      "target_username": null,
      "target_group_id": null,
      "conversation_id": "100311226008993792",
      "author": "lisi",
      "sources": [
        {
          "type": "word_list",
          "list_id": "100311111852621824",
          "list_name": "疑似诈骗",
          "word": "兼职刷单",
          "category": "fraud"
        }
      ],
      "categories": [
        "fraud"
      ],
      "suggestion": "review",
      "auto_actions": [],
      "report_count": 0,
      "priority": 2,
      "decision": null,
      "escalated_at": null,
      "content_available": true,
      "version": 1,
      "created_at": "2026-10-04T19:52:27.376Z",
      "closed_at": null,
      "close_reason": null
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	取值不合法，details.field 為 status、scene、category、source、priority、from 或 to

查詢稽核記錄

查詢一條稽核記錄，包括它引起的處置 actions。

GET/{org_name}/{app_name}/moderation/items/{item_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
item_id	String	稽核記錄 ID

請求示例

curl "$IM_API/$ORG/$APP/moderation/items/100311227732852736" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為稽核記錄物件。下面這條記錄先由詞庫送審，又被使用者舉報；稽核人員確認違規並撤回了訊息，之後改判為無違規：

{
  "item_id": "100311227732852736",
  "queue": "tenant",
  "status": "no_violation",
  "scene": "message",
  "target_type": "message",
  "target_id": "100311226352926720",
  "target_username": null,
  "target_group_id": null,
  "conversation_id": "100311226008993792",
  "author": "zhangsan",
  "sources": [
    {
      "type": "word_list",
      "list_id": "100311111852621824",
      "list_name": "疑似诈骗",
      "word": "兼职刷单",
      "category": "fraud"
    },
    {
      "type": "report",
      "count": 1,
      "reason": "fraud"
    }
  ],
  "categories": [
    "fraud"
  ],
  "suggestion": "review",
  "auto_actions": [],
  "report_count": 1,
  "priority": 0,
  "decision": {
    "result": "no_violation",
    "by_type": "account",
    "by": "文档（d***@example.com）",
    "note": "用户申诉，确认误判",
    "decided_at": "2026-10-04T19:26:40.754Z"
  },
  "escalated_at": null,
  "content_available": true,
  "version": 4,
  "created_at": "2026-10-04T19:21:00.386Z",
  "closed_at": "2026-10-04T19:26:32.494Z",
  "close_reason": "decided",
  "actions": [
    {
      "action_id": "100312620694765568",
      "kind": "recall_message",
      "authority": "tenant",
      "trigger": "review",
      "status": "done",
      "last_error": null,
      "created_at": "2026-10-04T19:26:32.497Z",
      "done_at": "2026-10-04T19:26:32.545Z"
    }
  ]
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	稽核記錄不存在，或不是你的稽核記錄

讀取稽核記錄的內容

讀取稽核記錄的內容快照和其中的舉報。內容是第一次被發現時的快照：之後訊息被撤回、資料被修改，讀到的仍是當時的內容。記錄結束 30 天后內容被清空，content 為 null，舉報的說明和證據同時清空。

GET/{org_name}/{app_name}/moderation/items/{item_id}/content

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
item_id	String	稽核記錄 ID

請求示例

curl "$IM_API/$ORG/$APP/moderation/items/100312464440164352/content" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
item_id	String	稽核記錄 ID
content	Object	內容快照，結構隨物件的型別不同，見內容快照；已清空時為 null
reports	Array<Object>	這條記錄中的舉報，見舉報詳情；沒有舉報時為空陣列

舉報使用者的記錄：profile 為舉報時的資料，之後資料又被修改過的，新的資料在 versions 中：

{
  "item_id": "100312464440164352",
  "content": {
    "profile": {
      "avatar_url": "",
      "nickname": "zhangsan"
    },
    "versions": [
      {
        "captured_at": "2026-10-04T19:27:35.838Z",
        "profile": {
          "avatar_url": "https://cdn.example.com/avatars/zhangsan.png",
          "nickname": "zhangsan"
        }
      }
    ]
  },
  "reports": [
    {
      "report_id": "100312464440164353",
      "reporter": "lisi",
      "reason": "abuse",
      "description": "多次辱骂",
      "evidence": [
        {
          "message_id": "100311226034159616",
          "conversation_id": "100311226008993792",
          "sender": "zhangsan",
          "type": "text",
          "body": {
            "text": "你这个**，周末一起吃饭"
          },
          "created_at": "2026-10-04T19:20:59.978Z"
        }
      ],
      "via": "openapi",
      "created_at": "2026-10-04T19:25:55.240Z"
    },
    {
      "report_id": "100312886391341057",
      "reporter": "wangwu",
      "reason": "ad",
      "description": "",
      "evidence": [],
      "via": "client",
      "created_at": "2026-10-04T19:27:35.841Z"
    }
  ]
}

訊息的記錄：

{
  "item_id": "100311227732852736",
  "content": {
    "body": {
      "text": "在家兼职刷单，日结300"
    },
    "created_at": "2026-10-04T19:21:00.055Z",
    "edits": [],
    "ext": null,
    "review_urls": [],
    "type": "text"
  },
  "reports": [
    {
      "report_id": "100312442805944321",
      "reporter": "lisi",
      "reason": "fraud",
      "description": "冒充兼职，要求先垫付",
      "evidence": [],
      "via": "openapi",
      "created_at": "2026-10-04T19:25:50.082Z"
    }
  ]
}

送審的資料（如暱稱）的記錄：

{
  "item_id": "100312702043291648",
  "content": {
    "fields": [
      {
        "captured_at": "2026-10-04T19:26:51.887Z",
        "name": "nickname",
        "value": "兼职刷单达人"
      }
    ]
  },
  "reports": []
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	稽核記錄不存在，或不是你的稽核記錄

作出結論

對一條稽核記錄作出結論：確認違規（可以同時處置），或無違規。也用於改判：作出結論後 30 天內可以把“確認違規”改為“無違規”。

POST/{org_name}/{app_name}/moderation/items/{item_id}/decide

結論的效果：

當前狀態	結論	效果
pending	violation	狀態改為 violation，執行選擇的處置；count_violation 為 true 時計入作者的違規，可能觸發自動處罰
pending	no_violation	狀態改為 no_violation
auto_violation	violation	狀態改為 violation。自動處置和違規已經有了，不重複，只執行這次另外選擇的處置
auto_violation、violation	no_violation	改判為無違規：刪除這條記錄引起的、按你的規則記下的違規，解除它遮蔽的檔案。已撤回的訊息不能恢復，已執行的禁言和封禁不會解除，需要時呼叫解除禁言、解封使用者
no_violation	violation	不允許，返回 403 permission_denied（not_revisable）。發現新的違規時等新的命中或舉報
expired（超過 30 天未處理）	兩者都可以	與 pending 相同；曾自動處置的與 auto_violation 相同

處置在結論提交後執行，響應中的處置通常還是 pending，稍後查詢稽核記錄可以看到結果。前一次請求已經成功、因為超時而重試的（結論相同、沒有新的處置），直接返回當前的記錄，不重複處置。

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
item_id	String	稽核記錄 ID

請求體

欄位	型別	必填	說明
decision	String	是	violation 確認違規，no_violation 無違規
actions	Array<Object>	否	同時執行的處置，只用於 violation，見處置
count_violation	Boolean	否	是否計入作者的違規，預設為 true。作者被盜號等情況可以傳 false；沒有作者的記錄忽略這一項
note	String	否	說明，最多 256 個字元，記入結論和操作日誌
version	Number	否	讀取到的記錄的 version。給出時與當前版本不一致返回 409 version_conflict，details.current 為當前的記錄，可以據此看到別人作出的結論

請求示例

確認違規，撤回訊息並禁言作者 1 小時：

curl -X POST "$IM_API/$ORG/$APP/moderation/items/100319140232822784/decide" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "violation",
    "actions": [
      { "kind": "recall_message" },
      { "kind": "mute_user", "scopes": ["chat", "group"], "duration_seconds": 3600 }
    ],
    "count_violation": true,
    "note": "发布刷单兼职",
    "version": 1
  }'

改判為無違規：

curl -X POST "$IM_API/$ORG/$APP/moderation/items/100319140232822784/decide" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "no_violation",
    "note": "用户申诉成功",
    "version": 2
  }'

響應

成功返回 200 OK，響應體為作出結論後的稽核記錄物件：

{
  "item_id": "100319140232822784",
  "queue": "tenant",
  "status": "violation",
  "scene": "message",
  "target_type": "message",
  "target_id": "100319139314270208",
  "target_username": null,
  "target_group_id": null,
  "conversation_id": "100311226008993792",
  "author": "lisi",
  "sources": [
    {
      "type": "word_list",
      "list_id": "100311111852621824",
      "list_name": "疑似诈骗",
      "word": "兼职刷单",
      "category": "fraud"
    }
  ],
  "categories": [
    "fraud"
  ],
  "suggestion": "review",
  "auto_actions": [],
  "report_count": 0,
  "priority": 2,
  "decision": {
    "result": "violation",
    "by_type": "app",
    "by": "App 凭据",
    "note": "发布刷单兼职",
    "decided_at": "2026-10-04T19:53:11.258Z"
  },
  "escalated_at": null,
  "content_available": true,
  "version": 2,
  "created_at": "2026-10-04T19:52:26.872Z",
  "closed_at": "2026-10-04T19:53:11.258Z",
  "close_reason": "decided",
  "actions": [
    {
      "action_id": "100319326401200128",
      "kind": "recall_message",
      "authority": "tenant",
      "trigger": "review",
      "status": "pending",
      "last_error": null,
      "created_at": "2026-10-04T19:53:11.263Z",
      "done_at": null
    },
    {
      "action_id": "100319326401200129",
      "kind": "mute_user",
      "authority": "tenant",
      "trigger": "review",
      "status": "pending",
      "last_error": null,
      "created_at": "2026-10-04T19:53:11.263Z",
      "done_at": null
    }
  ]
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	details.field 為 decision、note 或 actions：取值不合法，如禁言沒有給出 scopes、時長超出範圍
400	invalid_argument	details.reason 為 invalid_action：處置不適用於這個物件，如對使用者資料撤回訊息、對沒有本應用檔案的訊息遮蔽檔案、對沒有作者的記錄禁言；或者 no_violation 帶了處置
403	permission_denied	details.reason 為 not_revisable：把無違規改為違規；改判超過 30 天；記錄已轉交平臺，或因轉交、物件被刪除而結束；平臺作出的結論只有平臺能改判
404	not_found	稽核記錄不存在
409	version_conflict	version 與當前版本不一致，details.current 為當前的稽核記錄物件

{
  "error": {
    "code": "permission_denied",
    "message": "不能把无违规改为违规",
    "details": {
      "reason": "not_revisable"
    },
    "request_id": "ZGPHLUYW77R3JNTDAUUSGNTOHP"
  }
}

批次作出結論

對多條記錄作出同樣的結論，一次 1 到 100 條，例如處理一批刷屏的廣告。每條記錄分別處理，某條失敗不影響其他記錄。

• 只處理還沒有結論的記錄（pending、auto_violation，以及超過 30 天未處理而結束的），已被作出結論的返回 version_conflict，不在批次中改判；
• 處置只能是撤回訊息、撤回聊天室訊息、遮蔽檔案、清除資料和刪除聊天室屬性，不能禁言、封禁使用者，也不能封禁群和聊天室；
• 不需要 version，按每條記錄當前的版本處理。

POST/{org_name}/{app_name}/moderation/items/batch-decide

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
item_ids	Array<String>	是	稽核記錄 ID，1 到 100 個
decision	String	是	violation 或 no_violation
actions	Array<Object>	否	對每條記錄執行的處置，只用於 violation，見處置。每條記錄都必須適用這些處置，否則這條記錄失敗
count_violation	Boolean	否	是否計入作者的違規，預設為 true
note	String	否	說明，最多 256 個字元

請求示例

curl -X POST "$IM_API/$ORG/$APP/moderation/items/batch-decide" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_ids": ["100319140253794304", "100319140253794311", "100319140232822784"],
    "decision": "violation",
    "actions": [{ "kind": "recall_message" }],
    "count_violation": false,
    "note": "批量刷单广告"
  }'

響應

成功返回 200 OK，results 按請求的順序給出每條記錄的結果：成功的為 item_id 和作出結論後的記錄 item，失敗的為 item_id 和 error（code、message，有時有 details）。下例中第三條記錄已經有了結論（中間的記錄省略）：

{
  "results": [
    {
      "item": {
        "item_id": "100319140253794304",
        "queue": "tenant",
        "status": "violation",
        "scene": "message",
        "target_type": "message",
        "target_id": "100319139679174656",
        "target_username": null,
        "target_group_id": null,
        "conversation_id": "100311226008993792",
        "author": "lisi",
        "sources": [
          {
            "type": "word_list",
            "list_id": "100311111852621824",
            "list_name": "疑似诈骗",
            "word": "兼职刷单",
            "category": "fraud"
          }
        ],
        "categories": [
          "fraud"
        ],
        "suggestion": "review",
        "auto_actions": [],
        "report_count": 0,
        "priority": 2,
        "decision": {
          "result": "violation",
          "by_type": "app",
          "by": "App 凭据",
          "note": "批量刷单广告",
          "decided_at": "2026-10-04T19:53:27.498Z"
        },
        "escalated_at": null,
        "content_available": true,
        "version": 2,
        "created_at": "2026-10-04T19:52:26.878Z",
        "closed_at": "2026-10-04T19:53:27.498Z",
        "close_reason": "decided",
        "actions": [
          {
            "action_id": "100319394516697088",
            "kind": "recall_message",
            "authority": "tenant",
            "trigger": "review",
            "status": "pending",
            "last_error": null,
            "created_at": "2026-10-04T19:53:27.498Z",
            "done_at": null
          }
        ]
      },
      "item_id": "100319140253794304"
    },
    {
      "error": {
        "code": "version_conflict",
        "message": "数据已被其他人修改，请刷新后重试",
        "details": {
          "current": {
            "item_id": "100319140232822784",
            "queue": "tenant",
            "status": "violation",
            "scene": "message",
            "target_type": "message",
            "target_id": "100319139314270208",
            "target_username": null,
            "target_group_id": null,
            "conversation_id": "100311226008993792",
            "author": "lisi",
            "sources": [
              {
                "type": "word_list",
                "list_id": "100311111852621824",
                "list_name": "疑似诈骗",
                "word": "兼职刷单",
                "category": "fraud"
              }
            ],
            "categories": [
              "fraud"
            ],
            "suggestion": "review",
            "auto_actions": [],
            "report_count": 0,
            "priority": 2,
            "decision": {
              "result": "violation",
              "by_type": "app",
              "by": "App 凭据",
              "note": "发布刷单兼职",
              "decided_at": "2026-10-04T19:53:11.258Z"
            },
            "escalated_at": null,
            "content_available": true,
            "version": 2,
            "created_at": "2026-10-04T19:52:26.872Z",
            "closed_at": "2026-10-04T19:53:11.258Z",
            "close_reason": "decided",
            "actions": [
              {
                "action_id": "100319326401200128",
                "kind": "recall_message",
                "authority": "tenant",
                "trigger": "review",
                "status": "done",
                "last_error": null,
                "created_at": "2026-10-04T19:53:11.263Z",
                "done_at": "2026-10-04T19:53:11.320Z"
              },
              {
                "action_id": "100319326401200129",
                "kind": "mute_user",
                "authority": "tenant",
                "trigger": "review",
                "status": "done",
                "last_error": null,
                "created_at": "2026-10-04T19:53:11.263Z",
                "done_at": "2026-10-04T19:53:11.347Z"
              }
            ]
          }
        }
      },
      "item_id": "100319140232822784"
    }
  ]
}

錯誤

以下錯誤針對整個請求，這時沒有處理任何記錄。

HTTP 狀態碼	code	說明
400	invalid_argument	details.field 為 item_ids：為空、超過 100 個或有不合法的 ID
400	invalid_argument	details.reason 為 invalid_action：處置中有禁言、封禁

單條記錄的失敗可能為 not_found、version_conflict、invalid_argument（invalid_action）、permission_denied（not_revisable）。

轉交平臺

把一條未結束的稽核記錄轉交給平臺處理，用於你認為內容可能違法、需要平臺處理的情況。轉交後記錄由平臺稽核，你仍能檢視它的狀態（查詢稽核記錄列表時帶 escalated=true），但不能再作出結論。平臺已經有同一個物件的記錄時，這條記錄併入平臺的記錄，狀態改為 expired，close_reason 為 escalated。

POST/{org_name}/{app_name}/moderation/items/{item_id}/escalate

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
item_id	String	稽核記錄 ID

請求體

欄位	型別	必填	說明
note	String	否	轉交的說明，最多 256 個字元。沒有請求體時可以省略 Content-Type

請求示例

curl -X POST "$IM_API/$ORG/$APP/moderation/items/100312522434805760/escalate" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "群公告疑似违法，请平台处理"
  }'

響應

成功返回 200 OK，響應體為轉交後的稽核記錄物件，queue 為 platform：

{
  "item_id": "100312522434805760",
  "queue": "platform",
  "status": "pending",
  "scene": "report",
  "target_type": "group",
  "target_id": "100311656273281024",
  "target_username": null,
  "target_group_id": null,
  "conversation_id": null,
  "author": null,
  "sources": [
    {
      "type": "report",
      "count": 1,
      "reason": "other"
    },
    {
      "type": "escalation",
      "note": "群公告疑似违法，请平台处理"
    }
  ],
  "categories": [
    "other"
  ],
  "suggestion": null,
  "auto_actions": [],
  "report_count": 1,
  "priority": 2,
  "decision": null,
  "escalated_at": "2026-10-04T19:53:39.067Z",
  "content_available": true,
  "version": 2,
  "created_at": "2026-10-04T19:26:09.067Z",
  "closed_at": null,
  "close_reason": null
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	details.field 為 note：說明超過 256 個字元
403	permission_denied	details.reason 為 not_revisable：記錄已經結束或已經轉交
404	not_found	稽核記錄不存在

查詢平臺的處置

查詢平臺規則命中後，以平臺的身份對你的應用執行的處置，如撤回訊息、遮蔽檔案、封禁，按時間從新到舊分頁。只返回物件、類別和處置，不含內容。平臺撤回的訊息由平臺留證，平臺遮蔽的檔案和平臺的封禁你不能解除。

GET/{org_name}/{app_name}/moderation/platform-actions

路徑引數

org_name、app_name 見接入概述。

查詢引數

引數	型別	必填	說明
limit	Number	否	每頁的條數，預設 20，最大 100
cursor	String	否	上一頁返回的 next_cursor

請求示例

curl "$IM_API/$ORG/$APP/moderation/platform-actions" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 的每一項：

欄位	型別	說明
target_type、target_id、target_username、target_group_id	String	處置的物件，含義同稽核記錄物件
category	String	主要的類別
kind	String	處置的種類，見處置
status	String	pending 待執行、done 已執行、skipped 已跳過、failed 失敗
created_at	String	處置的時間
done_at	String	執行完成的時間，未完成為 null

next_cursor 為下一頁的遊標，沒有下一頁時為 null。

{
  "items": [
    {
      "category": "porn",
      "created_at": "2026-10-04T19:25:27.939Z",
      "done_at": "2026-10-04T19:25:27.995Z",
      "kind": "recall_message",
      "status": "done",
      "target_group_id": null,
      "target_id": "100312348417327104",
      "target_type": "message",
      "target_username": null
    }
  ],
  "next_cursor": null
}

查詢使用者的違規

查詢使用者的違規記錄（按時間從新到舊分頁）、當前的違規次數和最近的處罰。哪些情況計入違規見違規記錄與自動處罰。

GET/{org_name}/{app_name}/moderation/users/{username}/violations

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱

查詢引數

引數	型別	必填	說明
limit	Number	否	每頁的違規記錄條數，預設 20，最大 100
cursor	String	否	上一頁返回的 next_cursor

請求示例

curl "$IM_API/$ORG/$APP/moderation/users/zhaoliu/violations" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
items	Array<Object>	違規記錄，見下表
next_cursor	String	下一頁的遊標，沒有下一頁時為 null
violation_count	Number	當前的違規次數（180 天內、沒有被清除的），參與自動處罰規則
penalties	Array<Object>	最近 10 次處罰（自動處罰和結論中的禁言、封禁），見下表

items 的每一項：

欄位	型別	說明
violation_id	String	違規記錄 ID
scene	String	場景；舉報使用者、群、聊天室引起的為 report
category	String	類別
source	String	來源：sync 傳送前、儲存前檢查被拒絕，async 事後稽核自動處置，review 稽核人員確認違規
authority	String	按誰的規則：tenant 你的規則，platform 平臺規則
item_id	String	對應的稽核記錄 ID；傳送前、儲存前被拒絕的為 null。平臺規則的違規對應平臺的記錄，查詢它返回 404
created_at	String	違規的時間

penalties 的每一項：

欄位	型別	說明
kind	String	mute_user 全域性禁言、disable_user 封禁
params	Object	scopes 禁言的場景，duration_seconds 時長（null 為永久），reason 原因
status	String	pending 待執行、done 已執行、skipped 已跳過、failed 失敗
created_at	String	處罰的時間

{
  "items": [
    {
      "violation_id": "100312349927276546",
      "scene": "message",
      "category": "porn",
      "source": "async",
      "authority": "platform",
      "item_id": "100312349927276544",
      "created_at": "2026-10-04T19:25:27.941Z"
    },
    {
      "violation_id": "100312269543440386",
      "scene": "message",
      "category": "ad",
      "source": "async",
      "authority": "tenant",
      "item_id": "100312269543440384",
      "created_at": "2026-10-04T19:25:08.777Z"
    },
    {
      "violation_id": "100312045760544768",
      "scene": "message",
      "category": "ad",
      "source": "sync",
      "authority": "tenant",
      "item_id": null,
      "created_at": "2026-10-04T19:24:15.419Z"
    }
  ],
  "next_cursor": null,
  "penalties": [
    {
      "kind": "mute_user",
      "params": {
        "scopes": [
          "chat",
          "group"
        ],
        "duration_seconds": 3600,
        "reason": "内容安全：自动处罚（24 小时内违规 3 次）"
      },
      "status": "done",
      "created_at": "2026-10-04T19:25:27.943Z"
    }
  ],
  "violation_count": 3
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	使用者不存在或已刪除

清除使用者的違規

刪除使用者按你的規則記下的全部違規，違規次數相應減少，例如確認他的賬號曾被盜用。平臺規則的違規保留。已執行的禁言和封禁不會解除，penalties 中的記錄也保留。

DELETE/{org_name}/{app_name}/moderation/users/{username}/violations

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱

請求示例

curl -X DELETE "$IM_API/$ORG/$APP/moderation/users/lisi/violations" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，removed 為刪除的違規記錄數：

{
  "removed": 6
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	使用者不存在或已刪除

查詢統計

按天、按場景查詢內容安全的統計，以及你的待稽核記錄的數量。日期按北京時間劃分，數字最多落後 5 分鐘。

GET/{org_name}/{app_name}/moderation/stats

路徑引數

org_name、app_name 見接入概述。

查詢引數

引數	型別	必填	說明
from	String	是	開始日期，格式為 2026-10-01
to	String	是	結束日期，包含這一天，不能早於 from，與 from 相差最多 89 天（合計 90 天）
scene	String	否	只查詢這個場景，取值見稽核的內容和時機

請求示例

curl "$IM_API/$ORG/$APP/moderation/stats?from=2026-10-05&to=2026-10-05" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
days	Array<Object>	每天每個場景一項：date 日期，scene 場景（舉報使用者、群、聊天室的為 report），metrics 指標。沒有資料的日期和場景不返回，值為 0 的指標不返回
pending	Object	你的待稽核記錄（pending、auto_violation，不含轉交平臺的）：count 數量，oldest_wait_seconds 最早一條已等待的秒數，沒有時為 null

metrics 中的指標：

指標	說明
checked	檢查的次數
rejected、replaced、flagged	結果為拒絕、替換、送審的次數
auto_actioned	事後稽核自動處置的次數
provider_calls	呼叫第三方稽核的次數
platform_calls_text、platform_calls_image、platform_calls_audio、platform_calls_video	其中使用平臺賬號稽核文字、圖片、語音、影片的次數
cache_hits	圖片、語音、影片命中已有的稽核結果、沒有呼叫服務商的次數
provider_errors	呼叫第三方稽核失敗的次數
timeouts	同步稽核超時的次數（已停用，第三方稽核不再同步呼叫，為 0）
quota_skipped	超出每分鐘的事後稽核速率或平臺賬號每天的次數，只按詞庫檢查的次數
reports	舉報的次數

{
  "days": [
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 3,
        "rejected": 1,
        "replaced": 1,
        "reports": 1
      },
      "scene": "chatroom_message"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 1
      },
      "scene": "chatroom_profile"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 3,
        "rejected": 2,
        "replaced": 1
      },
      "scene": "friend_request"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 1,
        "rejected": 1
      },
      "scene": "group_member"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 3,
        "rejected": 1,
        "replaced": 1
      },
      "scene": "group_profile"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 3,
        "rejected": 2
      },
      "scene": "group_request"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "auto_actioned": 2,
        "checked": 15,
        "flagged": 2,
        "provider_calls": 8,
        "provider_errors": 2,
        "rejected": 8,
        "replaced": 3,
        "reports": 1,
        "timeouts": 2
      },
      "scene": "message"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "reports": 5
      },
      "scene": "report"
    },
    {
      "date": "2026-10-05",
      "metrics": {
        "checked": 13,
        "flagged": 1,
        "provider_calls": 2,
        "rejected": 4,
        "replaced": 2
      },
      "scene": "user_profile"
    }
  ],
  "pending": {
    "count": 7,
    "oldest_wait_seconds": 1783
  }
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	details.field 為 from 或 to：日期格式不對、to 早於 from 或超過 90 天；為 scene：場景不合法

代使用者舉報

以某個使用者的名義提交舉報，例如你在自己的網頁或客服系統中收集的使用者舉報。規則與客戶端舉報相同，包括可見範圍的檢查，但不受 report_enabled 和按使用者的頻率限制，改為每個應用每分鐘最多 600 次。

POST/{org_name}/{app_name}/moderation/reports

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
reporter	String	是	舉報人的使用者名稱。按他的可見範圍判斷能否舉報
target_type	String	是	舉報的物件：message 訊息、user 使用者、group 群、chatroom 聊天室、chatroom_message 聊天室訊息
message_id	String	視物件而定	被舉報的訊息 ID，target_type 為 message、chatroom_message 時必填
username	String	視物件而定	被舉報的使用者名稱，target_type 為 user 時必填
group_id	String	視物件而定	被舉報的群 ID，target_type 為 group 時必填
room_id	String	視物件而定	聊天室 ID，target_type 為 chatroom、chatroom_message 時必填
reason	String	是	舉報原因，見舉報原因
description	String	否	舉報說明，最多 500 個字元，不能包含控制字元（可以換行）
evidence_message_ids	Array<String>	否	證據訊息的 ID，最多 5 個，只用於舉報使用者和群：舉報使用者時必須是被舉報的使用者發的，舉報群時必須是這個群裡的訊息，並且都是舉報人能看到的

請求示例

舉報一條訊息：

curl -X POST "$IM_API/$ORG/$APP/moderation/reports" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reporter": "lisi",
    "target_type": "message",
    "message_id": "100311226352926720",
    "reason": "fraud",
    "description": "冒充兼职，要求先垫付"
  }'

舉報一個使用者，附上證據訊息：

curl -X POST "$IM_API/$ORG/$APP/moderation/reports" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reporter": "lisi",
    "target_type": "user",
    "username": "zhangsan",
    "reason": "abuse",
    "description": "多次辱骂",
    "evidence_message_ids": ["100311226034159616"]
  }'

響應

成功返回 201 Created，響應體為舉報物件。這個人已經舉報過同一個物件時返回 200 OK 和原來的舉報，不重複記錄，也不計入頻率限制。

{
  "report_id": "100312442805944321",
  "target_type": "message",
  "username": null,
  "message_id": "100311226352926720",
  "group_id": null,
  "room_id": null,
  "reason": "fraud",
  "status": "pending",
  "created_at": "2026-10-04T19:25:50.082Z"
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	details.field 為 reporter：沒有給出舉報人，或舉報人不存在
400	invalid_argument	details.field 為 target_type、reason、description 或 evidence_message_ids：取值不對，或說明、證據訊息超過上限
400	invalid_argument	details.reason 為 self_report：舉報自己或自己的訊息
400	invalid_argument	details.reason 為 invalid_evidence：舉報訊息、聊天室或聊天室訊息時附了證據訊息；證據訊息不存在、舉報人看不到、已撤回，不是被舉報的使用者發的，或不在被舉報的群裡
404	not_found	舉報的物件不存在，或舉報人看不到：訊息不存在、已撤回或不在舉報人的可見範圍內；使用者不存在或已刪除；群不存在、已解散，或是舉報人不在其中的私有群；聊天室不存在或已解散；聊天室訊息已不在最近的訊息中
429	rate_limited	超過每個應用每分鐘 600 次的限制，details.reason 為 request_rate

舉報自己的訊息時：

{
  "error": {
    "code": "invalid_argument",
    "message": "不能举报自己的消息",
    "details": {
      "reason": "self_report"
    },
    "request_id": "N6YRITSEUZQRKK6376PMPGLSXB"
  }
}

資料結構

稽核記錄物件

欄位	型別	說明
item_id	String	稽核記錄 ID
queue	String	tenant 你的佇列；platform 已轉交平臺
status	String	pending 待稽核；auto_violation 已自動處置，等待確認；violation 違規；no_violation 無違規；expired 已結束，原因見 close_reason
scene	String	場景，見稽核的內容和時機；舉報使用者、群、聊天室的記錄為 report
target_type	String	物件的型別：message 訊息、chatroom_message 聊天室訊息、user_profile 使用者資料、group_profile 群資料、group_member 群暱稱、group_request 入群申請、friend_request 好友申請、chatroom_profile 聊天室資料、chatroom_attribute 聊天室屬性、file 檔案、user 被舉報的使用者、group 被舉報的群、chatroom 被舉報的聊天室
target_id	String	物件的 ID：訊息 ID；聊天室訊息為 {聊天室 ID}:{消息 ID}；群資料、被舉報的群為群 ID；聊天室資料、被舉報的聊天室為聊天室 ID；聊天室屬性為 {聊天室 ID}:{属性的键}；檔案為檔案 ID。物件涉及使用者的（user、user_profile、group_member、group_request、friend_request）為 null，改用下面兩項
target_username	String	物件涉及的使用者：user、user_profile 為這個使用者，group_member 為被修改群暱稱的成員，group_request 為申請人或被邀請人，friend_request 為接收申請的人；其他物件和使用者已刪除時為 null
target_group_id	String	group_member、group_request 所在的群 ID，其他為 null
conversation_id	String	訊息所在的會話 ID，不是訊息時為 null
author	String	作者的使用者名稱：發出這條內容的使用者，被舉報的使用者。你的服務端提交的內容、被舉報的群和聊天室沒有作者，作者已刪除時也為 null
sources	Array<Object>	來源，見下表
categories	Array<String>	命中的類別
suggestion	String	機器的建議：block 攔截、review 人工稽核；只有舉報時為 null
auto_actions	Array<String>	已執行的自動處置，如 recall_message、block_file
report_count	Number	舉報的人數
priority	Number	優先順序：0 最高（含平臺強制處理的類別，或原因為詐騙、涉政、暴恐、涉及未成年人的舉報）；1 高（已自動處置，或 3 人以上舉報）；2 普通
decision	Object	結論，沒有結論時為 null。result 為 violation 或 no_violation；by_type 為作出結論的一方：account 控制檯成員、app 你的服務端、platform_admin 平臺；by 為作出結論的人，控制檯成員為姓名和部分隱藏的郵箱，服務端為 App 凭据，平臺為 null；note 為說明；decided_at 為時間
escalated_at	String	轉交平臺的時間，沒有轉交為 null
content_available	Boolean	內容快照是否還在。記錄結束 30 天后清空
version	Number	記錄的版本號，每次變化加一
created_at	String	建立時間
closed_at	String	結束的時間，未結束為 null
close_reason	String	結束的原因：decided 作出了結論；timeout 超過 30 天未處理；escalated 已併入平臺的記錄；target_deleted 物件已隨使用者刪除。未結束為 null
actions	Array<Object>	只在查詢稽核記錄和作出結論的響應中返回：這條記錄引起的處置，每項為 action_id、kind 處置的種類、authority（tenant 或 platform）、trigger（auto 自動處置、review 結論、penalty 自動處罰）、status（pending、done、skipped、failed）、last_error 跳過或失敗的原因、created_at、done_at

sources 的每一項，type 為來源的種類：

type	其他欄位
word_list	list_id 詞庫 ID、list_name 詞庫名稱、word 命中的詞條、category 類別。平臺詞庫的命中只有 platform（為 true）和 category
provider	provider 稽核服務商，如 aliyun、tencent、netease；labels 為服務商的結果，每項為 category 類別、label 服務商的原始標籤、score 分數
url_rejected	note：圖片的地址不能交給稽核服務的原因
report	count 舉報的次數、reason 舉報原因
escalation	note：轉交平臺的說明

內容快照

content 的結構隨 target_type 不同：

物件	欄位
message、chatroom_message	type 訊息型別，body、ext 訊息內容，created_at 傳送時間；edits 為之後編輯過的版本，每項為 body、ext、edited_at；review_urls 為訊息中的圖片、語音、影片的檢視地址
file	file_id 檔案 ID，kind 型別，name 檔名，review_urls 檢視地址
user、group、chatroom	profile 為舉報時的資料（使用者為 nickname、avatar_url；群為 name、avatar_url、description、announcement；聊天室為 name、description、announcement）；versions 為之後的資料，每項為 profile、captured_at
其他（資料、群暱稱、申請、聊天室屬性）	fields 為被稽核的欄位，每項為 name 欄位名、value 當時的值、captured_at 時間。同一個欄位之後的值也列在其中

訊息和資料合計最多保留 5 個版本，超過時保留第一個和最近的 4 個。

review_urls 的每一項：

欄位	型別	說明
source	String	快照中的原地址
url	String	檢視地址。本服務的檔案為 10 分鐘內有效的下載地址（已被遮蔽的檔案也可以檢視）；被平臺規則遮蔽的檔案為 null；外部地址就是原地址
external	Boolean	是否為外部地址。開啟外部地址時，對方的伺服器能看到訪問者的 IP，請謹慎在稽核人員的瀏覽器中直接載入

舉報詳情

欄位	型別	說明
report_id	String	舉報 ID
reporter	String	舉報人的使用者名稱，使用者已刪除時為 null
reason	String	舉報原因
description	String	舉報說明，沒有時為空字串
evidence	Array<Object>	證據訊息，每項為 message_id、conversation_id、sender 傳送者、type、body、created_at
via	String	client 客戶端舉報，openapi 你的服務端代使用者舉報
created_at	String	舉報的時間

處置

結論中 actions 的每一項為 kind 和它的引數。各種物件可以選擇的處置：

物件	可以選擇的 kind
message	recall_message；訊息中有本應用的檔案時另可 block_file
chatroom_message	recall_chatroom_message；訊息中有本應用的檔案時另可 block_file
file	block_file
user_profile、group_member、user	clear_profile
group_profile、group	clear_profile、disable_group
chatroom_profile、chatroom	clear_profile、disable_chatroom
chatroom_attribute	remove_chatroom_attribute
有作者的物件、user	另可 mute_user、disable_user

入群申請和好友申請的附言、理由不能清除，只能禁言或封禁作者。

kind	引數	說明
recall_message	—	撤回訊息，recalled.role 為 server
recall_chatroom_message	—	撤回聊天室訊息
block_file	file_ids：要遮蔽的檔案 ID，省略時為訊息中全部本應用的檔案	遮蔽檔案，之後下載返回 file_blocked
clear_profile	fields：要清除的欄位名，省略時為快照中的全部欄位。被舉報的使用者為 nickname、avatar_url；被舉報的群為 name、description、announcement、avatar_url；被舉報的聊天室為 name、description、announcement	把欄位清為空。只在欄位仍是當時被稽核的值時清除，之後改過的不受影響
remove_chatroom_attribute	—	刪除聊天室屬性，只在值沒有變化時刪除
mute_user	scopes：必填，chat、group、room 中的一個或多個；duration_seconds：1 到 315360000，省略為永久	全域性禁言作者
disable_user	duration_seconds：同上	封禁作者
disable_group	—	封禁群
disable_chatroom	—	封禁聊天室

處置都以你的應用的身份執行，與你呼叫對應介面的效果相同，可以照常解除。物件已不存在或已處於目標狀態（如訊息已被撤回）的，處置的狀態為 skipped。

舉報物件

欄位	型別	說明
report_id	String	舉報 ID
target_type	String	舉報的物件：message、user、group、chatroom、chatroom_message
username	String	被舉報的使用者名稱，target_type 為 user 時才有，其他為 null；使用者已刪除時為 null
message_id	String	被舉報的訊息 ID，target_type 為 message、chatroom_message 時才有，其他為 null
group_id	String	被舉報的群 ID，target_type 為 group 時才有，其他為 null
room_id	String	聊天室 ID，target_type 為 chatroom、chatroom_message 時才有，其他為 null
reason	String	舉報原因，見舉報原因
status	String	pending 處理中，closed 已處理
created_at	String	舉報的時間