Moderation config and word lists

Maintain word lists, change moderation settings and check text from your server — the same as "Config", "Word lists" and "Try it" under "Moderation" in the console. For what the settings and word lists mean, see Moderation; for doing it in the console, see Moderation configuration.

For example, create a word list that rejects diversion, add two words, then try a piece of text:

bash

LIST=$(curl -s -X POST "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "导流", "action": "reject", "category": "ad" }' | jq -r .list_id)

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/$LIST/words/batch" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "words": ["加微信", "加QQ"] }'

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "scene": "message", "text": "有需要请加 微 信" }'
# 词库修改通常 1 秒内生效；结果的 action 为 reject

You want to	API
Create, change or delete word lists	Create a word list, Update a word list, Delete a word list
Add, delete or list words	Add words, Delete words, List words
Check whether a piece of text would be blocked	Check text
Turn third-party moderation on or off, set up automatic penalties, check server-submitted content too	Update moderation config

When changes apply: changes to config, word lists and words usually apply within a second, at most 30 seconds. Verify right away with Check text.
Moderation accounts: third-party moderation accounts can only be added and chosen in the console; these APIs can't change provider_account_id. Choose an account for the app in the console before turning on third-party moderation for a scene.
Platform settings: platform in the config is the platform's settings for this app and is read-only.
Audit log: requests changing config, word lists and words are written to the audit log, with the server key used as the operator.
Call quota: adding and deleting words counts toward the app's OpenAPI call quota per word, see Batch APIs.

Get moderation config

Gets the app's current moderation config. scenes returns settings for every scene, with defaults for those never changed.

GET/{org_name}/{app_name}/moderation/config

Path parameters

For org_name and app_name, see Server overview.

Example request

bash

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

Response

Returns 200 OK with a moderation config object.

json

{
  "scenes": {
    "chatroom_attribute": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "chatroom_message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "chatroom_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "friend_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_member": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "media_upload": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "user_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    }
  },
  "custom_message_check": "strings",
  "provider_account_id": null,
  "sync_timeout_ms": 800,
  "on_timeout": "pass",
  "penalty_rules": [
    {
      "window_hours": 24,
      "threshold": 3,
      "categories": null,
      "action": "mute",
      "mute_scopes": [
        "chat",
        "group"
      ],
      "duration_seconds": 3600
    },
    {
      "window_hours": 168,
      "threshold": 10,
      "categories": null,
      "action": "disable",
      "mute_scopes": null,
      "duration_seconds": 604800
    }
  ],
  "platform": {
    "rules_enabled": true,
    "scenes": {},
    "daily_quota": 100000,
    "enforced_categories": [
      "politics",
      "terrorism",
      "porn"
    ],
    "inherited_scenes": true,
    "inherited_daily_quota": true
  },
  "version": 8,
  "updated_at": "2026-10-04T19:37:43.590Z"
}

Update moderation config

Pass only what you want to change; anything left out stays as it is:

scenes merges per scene: only the scenes and fields in the request change;
category_actions merges per category: null for a category restores its default handling;
penalty_rules is replaced as a whole: pass all the new rules, or null for no automatic penalties.

If nothing actually changes, version stays the same.

PATCH/{org_name}/{app_name}/moderation/config

Path parameters

For org_name and app_name, see Server overview.

Request body

Field	Type	Required	Description
`scenes`	Object	No	Scenes to change: keys are scenes, values are the fields of Scene settings to change
`custom_message_check`	String	No	How custom messages are checked: `strings` checks every string value in `body`, `off` doesn't check
`category_actions`	Object	No	Category handling to change: keys are categories, values are the fields of Category handling to change, or `null` (restore default)
`sync_timeout_ms`	Number	Deprecated, has no effect; 800 by default
`on_timeout`	String	Deprecated, has no effect; `pass` by default
`penalty_rules`	Array<Object>	No	Automatic penalty rules, at most 5, replaced as a whole, see Automatic penalty rules; `null` or an empty array means no automatic penalties
`version`	Number	No	The `version` you read. If given and different from the current version, returns `409 version_conflict`, see Concurrent changes

The body can't contain provider_account_id (even as null), or you get 400 invalid_argument. platform may appear but is ignored, so you can edit the config you fetched and submit it whole (minus provider_account_id).

Example request

Check group profiles submitted by your server against your rules too, send ads that third-party moderation suggests blocking to review instead, and set the wait to 1 second:

bash

curl -X PATCH "$IM_API/$ORG/$APP/moderation/config" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenes": { "group_profile": { "include_server_sent": true } },
    "category_actions": { "ad": { "block": "review" } },
    "sync_timeout_ms": 1000,
    "version": 8
  }'

Response

Returns 200 OK with the updated moderation config object.

json

{
  "scenes": {
    "chatroom_attribute": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "chatroom_message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "chatroom_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "friend_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_member": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "group_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "group_request": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "media_upload": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": false
    },
    "message": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    },
    "user_profile": {
      "enabled": true,
      "text_provider": "off",
      "media_provider": "off",
      "include_server_sent": true
    }
  },
  "custom_message_check": "strings",
  "provider_account_id": null,
  "category_actions": {
    "ad": {
      "block": "review",
      "review": "review"
    }
  },
  "sync_timeout_ms": 1000,
  "on_timeout": "pass",
  "penalty_rules": [
    {
      "window_hours": 24,
      "threshold": 3,
      "categories": null,
      "action": "mute",
      "mute_scopes": [
        "chat",
        "group"
      ],
      "duration_seconds": 3600
    },
    {
      "window_hours": 168,
      "threshold": 10,
      "categories": null,
      "action": "disable",
      "mute_scopes": null,
      "duration_seconds": 604800
    }
  ],
  "platform": {
    "rules_enabled": true,
    "scenes": {},
    "daily_quota": 100000,
    "enforced_categories": [
      "politics",
      "terrorism",
      "porn"
    ],
    "inherited_scenes": true,
    "inherited_daily_quota": true
  },
  "version": 9,
  "updated_at": "2026-10-04T19:49:55.426Z"
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	Invalid value; `details.field` names the field, such as `scenes` (no such scene), `sync_timeout_ms`, `on_timeout`, `custom_message_check`, `category_actions`, `penalty_rules`; `provider_account_id` when the body contains it
400	`invalid_argument`	`details.reason` is `unsupported_scene`: the scene doesn't support that review mode, such as `media_provider` `async` for a scene without media, see Scene settings
400	`invalid_argument`	`details.reason` is `provider_account_required`: third-party moderation was turned on, but the app hasn't chosen a moderation account in the console
409	`limit_exceeded`	`details.reason` is `penalty_rule_limit`: more than 5 automatic penalty rules
409	`version_conflict`	`version` differs from the current version; `details.current` holds the current `version` and `updated_at`

json

{
  "error": {
    "code": "version_conflict",
    "message": "数据已被其他人修改，请刷新后重试",
    "details": {
      "current": {
        "updated_at": "2026-10-04T19:49:55.426Z",
        "version": 9
      }
    },
    "request_id": "7FPY7Z2Q5BVEIVC7MDNLTVJFJN"
  }
}

Word lists

Each app can have up to 20 word lists with up to 10000 words each, 50000 words in total. For word list properties and matching rules, see Word lists.

List word lists

Lists all the app's word lists, unpaginated, in creation order.

GET/{org_name}/{app_name}/moderation/word-lists

Path parameters

For org_name and app_name, see Server overview.

Example request

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK; items is an array of word list objects.

json

{
  "items": [
    {
      "list_id": "100311111194116096",
      "name": "广告导流",
      "kind": "block",
      "action": "reject",
      "match_mode": "contains",
      "category": "ad",
      "scenes": null,
      "enabled": true,
      "word_count": 4,
      "created_at": "2026-10-04T19:20:32.603Z",
      "updated_at": "2026-10-04T19:20:41.046Z"
    },
    {
      "list_id": "100311111538049024",
      "name": "不文明用语",
      "kind": "block",
      "action": "replace",
      "match_mode": "contains",
      "category": "abuse",
      "scenes": null,
      "enabled": true,
      "word_count": 2,
      "created_at": "2026-10-04T19:20:32.683Z",
      "updated_at": "2026-10-04T19:30:08.569Z"
    }
  ]
}

Create a word list

POST/{org_name}/{app_name}/moderation/word-lists

Path parameters

For org_name and app_name, see Server overview.

Request body

Field	Type	Required	Description
`name`	String	Yes	Name, 1 to 64 characters with no control characters, unique within the app
`kind`	String	No	Kind: `block` (default) or `allow`. Can't be changed after creation
`action`	String	Depends on kind	Required for block lists: `reject`, `replace` or `review`. Not allowed for allow lists
`match_mode`	String	No	Match mode: `contains` (default) or `exact`. Allow lists can only use `contains`
`category`	String	No	Category recorded on a match, `custom` by default
`scenes`	Array<String>	No	Scenes the list applies to; can't be empty. Omitted or `null` means all scenes
`enabled`	Boolean	No	Whether the list is enabled, `true` by default

Example request

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "联系方式导流",
    "kind": "block",
    "action": "review",
    "match_mode": "contains",
    "category": "ad",
    "scenes": ["message", "chatroom_message"],
    "enabled": true
  }'

Response

Returns 201 Created with a word list object.

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流",
  "kind": "block",
  "action": "review",
  "match_mode": "contains",
  "category": "ad",
  "scenes": [
    "message",
    "chatroom_message"
  ],
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:21.669Z"
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	Invalid value; `details.field` names the field: `name` when another list in the app has that name, `scenes` when it's an empty array
400	`invalid_argument`	`details.reason` is `unsupported_action`: a block list without `action`, or an allow list with one
409	`limit_exceeded`	`details.reason` is `word_list_limit`: the app already has 20 word lists

Get a word list

GET/{org_name}/{app_name}/moderation/word-lists/{list_id}

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Example request

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK with a word list object.

Errors

HTTP status	`code`	Description
404	`not_found`	The word list doesn't exist or doesn't belong to this app

Update a word list

Changes a word list's properties; pass only the fields to change. The kind kind can't be changed.

PATCH/{org_name}/{app_name}/moderation/word-lists/{list_id}

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Request body

Same fields as Create a word list, all optional, without kind. null for scenes makes the list apply to all scenes.

Example request

bash

curl -X PATCH "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "联系方式导流（消息）",
    "action": "reject",
    "scenes": null
  }'

Response

Returns 200 OK with the updated word list object.

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流（消息）",
  "kind": "block",
  "action": "reject",
  "match_mode": "contains",
  "category": "ad",
  "scenes": null,
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:28.250Z"
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	Invalid value; `details.field` names the field, `kind` when the request contains it
400	`invalid_argument`	`details.reason` is `unsupported_action`: the block list would have no action, or `action` was set on an allow list
404	`not_found`	The word list doesn't exist

Delete a word list

Deletes a word list and all its words. This can't be undone.

DELETE/{org_name}/{app_name}/moderation/word-lists/{list_id}

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Example request

bash

curl -X DELETE "$IM_API/$ORG/$APP/moderation/word-lists/100318861361938432" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 204 No Content with no body.

Errors

HTTP status	`code`	Description
404	`not_found`	The word list doesn't exist or was already deleted

List words

Lists a word list's words page by page, sorted by normalized word, see Pagination.

GET/{org_name}/{app_name}/moderation/word-lists/{list_id}/words

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Query parameters

Parameter	Type	Required	Description
`prefix`	String	No	Only return words starting with it. Matched after normalization, so `加 Q` is the same as `加q`
`limit`	Number	No	Items per page, 20 by default, at most 500
`cursor`	String	No	The `next_cursor` from the previous page

Example request

bash

curl "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words?limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK:

Field	Type	Description
`items`	Array<Object>	Array of word objects
`next_cursor`	String	Cursor for the next page, `null` when there's none

json

{
  "items": [
    {
      "word": "qq号",
      "original": "ｑｑ号",
      "created_at": "2026-10-04T19:50:33.933Z"
    },
    {
      "word": "二维码进群",
      "original": "二维码进群",
      "created_at": "2026-10-04T19:50:33.933Z"
    }
  ],
  "next_cursor": "二维码进群"
}

Errors

HTTP status	`code`	Description
404	`not_found`	The word list doesn't exist

Add words

Adds 1 to 1000 words to a word list. Each word is normalized first; words equal after normalization to an existing word (or another word in the same request) are duplicates, invalid words aren't added, and the rest are added as usual.

POST/{org_name}/{app_name}/moderation/word-lists/{list_id}/words/batch

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Request body

Field	Type	Required	Description
`words`	Array<String>	Yes	Words to add, 1 to 1000. Block words are 2 to 32 characters after normalization, allow words 2 to 64; at most 64 characters as submitted, with no control characters

Example request

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["加QQ", "加 Q Q", "ｑｑ号", "扣扣", "x", "二维码进群"]
  }'

Response

Returns 200 OK:

Field	Type	Description
`added`	Number	Number of words added
`duplicated`	Array<String>	Duplicate words (as submitted)
`invalid`	Array<Object>	Invalid words, each with the submitted `word` and a `reason`: `too_short`, `too_long` or `control_character`

In the example, "加 Q Q" normalizes to 加qq, a duplicate of "加QQ" submitted alongside it; "ｑｑ号" normalizes to qq号:

json

{
  "added": 4,
  "duplicated": [
    "加 Q Q"
  ],
  "invalid": [
    {
      "reason": "too_short",
      "word": "x"
    }
  ]
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`details.field` is `words`: `words` is empty or has more than 1000 items
404	`not_found`	The word list doesn't exist
409	`limit_exceeded`	`details.reason` is `word_limit`: the list would exceed 10000 words, or the app 50000 in total. Nothing in the batch is added

Delete words

Deletes 1 to 1000 words from a word list. Words can be given as submitted or normalized, and are deleted by their normalized form; words that don't exist are ignored.

POST/{org_name}/{app_name}/moderation/word-lists/{list_id}/words/batch-delete

Path parameters

For org_name and app_name, see Server overview.

Parameter	Type	Description
`list_id`	String	Word list ID

Request body

Field	Type	Required	Description
`words`	Array<String>	Yes	Words to delete, 1 to 1000

Example request

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/word-lists/100318615084990464/words/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["扣扣", "加 qq", "不存在的词"]
  }'

Response

Returns 200 OK; removed is the number of words deleted:

json

{
  "removed": 2
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`details.field` is `words`: `words` is empty or has more than 1000 items
404	`not_found`	The word list doesn't exist

Check text

Checks a piece of text or several fields against all the app's current rules and returns the result and matched words — for verifying word list changes, or pre-checking user input in your own business. The check treats the content as client-submitted (both platform rules and your rules apply), and creates no review items or violations and isn't counted in statistics.

Platform word list matches only return platform and the category, not the word list or matched word.

POST/{org_name}/{app_name}/moderation/text-check

Path parameters

For org_name and app_name, see Server overview.

Request body

Field	Type	Required	Description
`scene`	String	Yes	Scene; checks with that scene's word lists and settings. Values in What's checked and when
`text`	String	One of the two	A piece of text to check
`fields`	Object	One of the two	Several fields to check: keys are field names, values are text; at most 10 together with `text`
`with_provider`	Boolean	No	Whether to also use smart review, `true` by default: keywords and smart review run together, and smart review is called synchronously when text review is on for this scene, counting toward usage and fees. If smart review does not run, only the keyword result is used and the reason is in `provider_skipped`. `false` checks keywords only

Example request

Check a piece of text:

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scene": "message",
    "text": "想要资料请扫二维码进群，你个笨蛋"
  }'

Check several fields:

bash

curl -X POST "$IM_API/$ORG/$APP/moderation/text-check" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scene": "group_profile",
    "fields": { "name": "周末兼职刷单群", "announcement": "欢迎新人" }
  }'

Response

Returns 200 OK. With only text, the body is a check result object:

json

{
  "action": "reject",
  "hits": [
    {
      "list_id": "100318615084990464",
      "list_name": "联系方式导流（消息）",
      "category": "ad",
      "action": "reject",
      "word": "二维码进群",
      "start": 6,
      "end": 11
    },
    {
      "list_id": "100311111538049024",
      "list_name": "不文明用语",
      "category": "abuse",
      "action": "replace",
      "word": "笨蛋",
      "start": 14,
      "end": 16
    }
  ],
  "provider_result": null,
  "text": "想要资料请扫二维码进群，你个**"
}

With fields, the body is { "fields": { field name: check result object } }; if text was given too, the result has an extra field named text:

json

{
  "fields": {
    "announcement": {
      "action": "reject",
      "hits": [],
      "provider_result": {
        "categories": [
          "gambling"
        ],
        "suggestion": "block"
      },
      "text": "欢迎新人"
    },
    "name": {
      "action": "review",
      "hits": [
        {
          "list_id": "100311111852621824",
          "list_name": "疑似诈骗",
          "category": "fraud",
          "action": "review",
          "word": "兼职刷单",
          "start": 2,
          "end": 6
        }
      ],
      "provider_result": {
        "categories": [
          "vulgar"
        ],
        "suggestion": "review"
      },
      "text": "周末兼职刷单群"
    }
  }
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`details.field` is `scene`: invalid scene; or `fields`: neither `text` nor `fields` given, or more than 10 together

Data structures

Moderation config object

Field	Type	Description
`scenes`	Object	Settings for every scene: keys are scenes, values are Scene settings
`custom_message_check`	String	How custom messages are checked: `strings` checks every string value in `body` (default), `off` doesn't check
`provider_account_id`	String	ID of the moderation account chosen for the app in the console, `null` if none
`category_actions`	Object	Changed category handling: keys are categories, values are Category handling. Unchanged categories use defaults; omitted when none were changed
`sync_timeout_ms`	Number	Deprecated, has no effect; 800 by default
`on_timeout`	String	Deprecated, has no effect; `pass` by default
`penalty_rules`	Array<Object>	Automatic penalty rules; `null` or an empty array when there are none
`platform`	Object	The platform's settings for this app, read-only, see below
`version`	Number	Config version, incremented on every change. `1` for apps never changed
`updated_at`	String	Time of the last change, `null` if never changed

Fields of platform:

Field	Type	Description
`rules_enabled`	Boolean	Whether platform rules apply to this app
`scenes`	Object	Scenes where the platform runs third-party moderation for this app on its account: keys are scenes, values hold `text_provider` and `media_provider`; an empty object if none
`daily_quota`	Number	Daily review limit for this app on the platform account; `0` means unlimited
`enforced_categories`	Array<String>	Categories the platform enforces
`inherited_scenes`	Boolean	Whether `scenes` is the platform default (not set specifically for this app)
`inherited_daily_quota`	Boolean	Whether `daily_quota` is the platform default

Scene settings

Field	Type	Description
`enabled`	Boolean	Whether this scene is checked against your rules, `true` by default. When `false`, only platform rules apply
`text_provider`	String	Third-party text review: `off` (default) or `async` (after the content is sent or saved). The old value `sync` is treated as `async`
`media_provider`	String	Third-party review of images, voice and video: `off` (default) or `async` (after the content is sent or saved)
`include_server_sent`	Boolean	Whether content submitted by your server and the console is checked against your rules too, `false` by default

Third-party review always runs after content is sent or saved; sending and saving only check word lists and never wait for the provider. Violating messages are recalled and violating profiles and avatars are cleared automatically; add words to a word list for content that must never go out.

Values each scene supports:

Scene	`text_provider`	`media_provider`	`include_server_sent`
`message`, `chatroom_message`	`off`, `async`	`off`, `async`	Configurable
`user_profile`, `group_profile`	`off`, `async`	`off`, `async` (avatars)	Configurable
`group_member`, `group_request`, `friend_request`, `chatroom_profile`	`off`, `async`	`off`	Configurable
`media_upload`	`off`	`off`, `async`	Settable
`chatroom_attribute`	`off`	`off`	Only `false`

When any scene's text_provider or media_provider isn't off, the app must have chosen a moderation account in the console.

Category handling

How third-party moderation results are handled; categories the platform enforces aren't affected.

Field	Type	Description
`block`	String	On suggest block: `reject` (default) or `review`
`review`	String	On suggest manual review: `review` (default) or `none`

Automatic penalty rules

Field	Type	Description
`window_hours`	Number	Time window, 1 to 720 hours
`threshold`	Number	Violations within the window, 1 to 1000
`categories`	Array<String>	Only count violations in these categories; `null` counts all
`action`	String	Penalty: `mute` (global mute) or `disable` (ban)
`mute_scopes`	Array<String>	Mute scopes, required when `action` is `mute`: one or more of `chat`, `group`, `room`; `null` when `action` is `disable`
`duration_seconds`	Number	Penalty duration, 1 to 315360000 seconds (10 years); `null` is permanent

How rules are applied: see Violations and automatic penalties.

Word list object

Field	Type	Description
`list_id`	String	Word list ID
`name`	String	Name
`kind`	String	Kind: `block` or `allow`
`action`	String	Action: `reject`, `replace` or `review`; `null` for allow lists
`match_mode`	String	Match mode: `contains` or `exact`
`category`	String	Category recorded on a match
`scenes`	Array<String>	Scenes it applies to; `null` means all scenes
`enabled`	Boolean	Whether it's enabled
`word_count`	Number	Number of words
`created_at`	String	Creation time
`updated_at`	String	Time the list or its words last changed

json

{
  "list_id": "100318615084990464",
  "name": "联系方式导流",
  "kind": "block",
  "action": "review",
  "match_mode": "contains",
  "category": "ad",
  "scenes": [
    "message",
    "chatroom_message"
  ],
  "enabled": true,
  "word_count": 0,
  "created_at": "2026-10-04T19:50:21.669Z",
  "updated_at": "2026-10-04T19:50:21.669Z"
}

Word object

Field	Type	Description
`word`	String	The normalized word, used for matching
`original`	String	The word as submitted
`created_at`	String	When it was added

Check result object

Field	Type	Description
`action`	String	Result: `pass`, `reject`, `replace` or `review`
`text`	String	The text after replacement; same as the original when no replace word matched
`hits`	Array<Object>	Matched word lists, see below; an empty array when nothing matched
`provider_result`	Object	Smart review result: `suggestion` (`pass`, `review` for suggest manual review, `block` for suggest block) and `categories` (categories). `null` when not called or the call failed
`provider_skipped`	String	Why smart review did not run this time; `null` when it ran or `with_provider` is `false`: `not_enabled` text review is not on for this scene, `no_account` text review is not available from the platform yet, `not_entitled` the plan does not include platform moderation, `quota` today's review quota is used up and the review balance is too low, `failed` smart review is temporarily unavailable. The result then comes from keywords only

Each item of hits:

Field	Type	Description
`list_id`	String	Word list ID. Absent for platform word list matches
`list_name`	String	Word list name. Absent for platform word list matches
`platform`	Boolean	`true` for platform word list matches, which only carry `category`; absent for your word lists
`category`	String	The word list's category
`action`	String	The word list's action
`word`	String	The matched word (normalized)
`start`, `end`	Number	Position of the match in the original, in characters from 0, `end` exclusive

Moderation config and word lists ​

Get moderation config ​

Path parameters ​

Example request ​

Response ​

Update moderation config ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Word lists ​

List word lists ​

Path parameters ​

Example request ​

Response ​

Create a word list ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Get a word list ​

Path parameters ​

Example request ​

Response ​

Errors ​

Update a word list ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Delete a word list ​

Path parameters ​

Example request ​

Response ​

Errors ​

List words ​

Path parameters ​

Query parameters ​

Example request ​

Response ​

Errors ​

Add words ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Delete words ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Check text ​

Path parameters ​

Request body ​

Example request ​

Response ​

Errors ​

Data structures ​

Moderation config object ​

Scene settings ​

Category handling ​

Automatic penalty rules ​

Word list object ​

Word object ​

Check result object ​

Moderation config and word lists

Get moderation config

Path parameters

Example request

Response

Update moderation config

Path parameters

Request body

Example request

Response

Errors

Word lists

List word lists

Path parameters

Example request

Response

Create a word list

Path parameters

Request body

Example request

Response

Errors

Get a word list

Path parameters

Example request

Response

Errors

Update a word list

Path parameters

Request body

Example request

Response

Errors

Delete a word list

Path parameters

Example request

Response

Errors

List words

Path parameters

Query parameters

Example request

Response

Errors

Add words

Path parameters

Request body

Example request

Response

Errors

Delete words

Path parameters

Request body

Example request

Response

Errors

Check text

Path parameters

Request body

Example request

Response

Errors

Data structures

Moderation config object

Scene settings

Category handling

Automatic penalty rules

Word list object

Word object

Check result object