敏感词

敏感词是发送时的同步过滤：词表按应用保存，命中后按处置动作 block（拒绝，1010）或 replace（入库并掩码）处理。它与「内容审核」的任务复核是两件事：敏感词决定消息是否放行，审核任务是对已放行消息的事后复核。

概念​

处置动作发送结果后续
block（默认）返回 1010 SENSITIVE_WORD，消息不入库无审核任务、无 messageId
replace消息入库，命中词替换为 ***生成 action=replaced 审核任务，可事后 reject
  • 控制台口径单应用词表 ≤500 条；Open API 另有增量增删接口（sensitiveword.add/batch.add/delete/batch.delete）。
  • 写入带 replaceWord 的词条会把该词处置切到 replace；整体设置接口用 action 统一指定。
  • 词表随应用状态持久化；关闭 sensitive_words 服务只门禁管理接口，已有词表仍生效。
  • 大小写/全半角不做归一化（按字面包含匹配）；配置时需覆盖实际变体。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#sensitive（tab #sensitive：敏感词）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 确定处置策略

    强合规场景用 block；需要保留上下文/人工复核用 replace。

  2. 维护词表

    控制台可直接编辑；批量场景用 Open API 增量接口，避免整体覆盖误删。

  3. 验证命中

    发送含词消息：block 应返回 1010；replace 应成功且正文出现 ***。

  4. 与审核联动

    replace 命中会生成审核任务；在「内容审核」中 approve/reject。

参数表​

操作方法与路径请求体
读取词表GET /api/admin/apps/{appkey}/sensitive-words—（返回 words/action）
整体设置POST /api/admin/apps/{appkey}/sensitive-words{words:[...],action?}
Open API 整体设置POST /im/v2/sensitive-word/set{words:[...],action:block|replace}
Open API 增量添加POST /im/v2/sensitiveword/add{word,replaceWord?}
Open API 批量添加/删除/im/v2/sensitiveword/batch/add、/sensitiveword/batch/delete词汇数组

示例​

设置 replace 词表并验证​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/sensitive-words" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"words":["违禁词","广告词"],"action":"replace"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/sensitive-words" \
  -H 'X-Admin-Secret: dev-admin'

# 发送含词消息后，replace 会成功且正文被掩码
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/messages" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"from":"alice","conversationType":1,"targetId":"bob","content":{"type":"text","text":"这是违禁词测试"}}'

Open API 增量增删（应用服务器签名）​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/sensitiveword/add" \
  -H 'App-Key: demo' -H 'Nonce: n1' -H 'Timestamp: 1750000000000' -H 'Signature: <sig>' \
  -H 'content-type: application/json' \
  -d '{"word":"刷单","replaceWord":"***"}'

常见问题​

block 和 replace 能按词分别设置吗？​

增量接口里 replaceWord 会把该词切到 replace；整体设置接口的 action 对整表生效。

命中后客户端收到什么？​

block 返回 1010，消息不出现；replace 正常收到消息，正文中的词已变成 ***。

为什么英文大小写变体没命中？​

匹配按字面包含，不做大小写归一化；需要把常见变体都加入词表。

关闭敏感词服务后还能管理词表吗？​

不能，管理接口返回 1021；但已有词表的过滤仍生效。

相关链接​