消息合规API

● 应用场景

智齿在线客服系统支持对访客消息进行合规检测。管理员在后台配置合规规则并绑定第三方风控接口后，每条访客消息发送时，智齿系统会调用第三方接口进行内容检测，根据返回结果对消息进行合规标记。

消息合规校验可以屏蔽客户发来的违规文本和图片，保护客服不被骚扰内容伤害。客户消息会先通过「客户敏感词」过滤，再按照「消息合规规则」进行检测。

第三方需按照本文档规范实现接口，供智齿系统调用。

● 如何设置

合规检测的配置分为两步：先在「接口管理」中添加接口，再在「消息合规校验」中创建规则并关联接口。

步骤一：添加接口

进入「管理中心 - 接口管理」，点击添加接口，配置以下信息：

添加请求参数

参数	类型	必填	描述
companyId	String	是	公司 ID，智齿系统中的企业唯一标识
cid	String	是	会话 ID，当前会话的唯一标识
msgId	String	是	消息 ID，当前消息的唯一标识
staffId	String	否	当前接待客服 ID。待分配阶段（未分配客服）时为空字符串
msgType	Integer	是	消息类型。0=文本，1=图片，2=音频，3=视频，4=文件，5=对象（卡片），7=邮件
objMsgType	Integer	否	对象消息子类型。仅 msgType=5 时有值，标识具体的对象类型。其他 msgType 时为 null
content	String	是	消息内容。文本消息为文本内容；图片/音频/视频/文件消息为资源 URL；对象消息为 JSON 字符串

添加输出参数

参数	类型	必填	描述
msgId	String	是	消息 ID
msgTag	String	是	0-合规; 1-不合规,宽松屏蔽; 2-不合规,严格屏蔽

步骤二：添加合规规则

进入「在线客服 - 设置 - 会话设置 - 敏感词设置 - 消息合规校验」，点击添加规则：

配置项	说明
规则名称	自定义规则名称
适用接待方案	选择该规则生效的接待方案范围
检测接口	关联步骤一中已添加的接口
检测消息类型	勾选需要检测的消息类型：文本、图片、音频、视频、文件、卡片、邮件
状态	开关控制。开启后，适用接待方案下的客户消息将经过本规则检测

● 返回参数

第三方接口需按以下规范返回检测结果。返回参数必须在 3 秒内推送，否则消息将视为合规，正常展示。

返回参数：

参数	类型	必填	描述
msgId	String	否	消息 ID，与请求中的 msgId 对应
msgTag	Integer	是	检测结果标记

msgTag 取值说明：

msgTag	说明	客服侧展示效果
0	合规	正常展示消息内容
1	不合规，宽松屏蔽	默认屏蔽，客服可点击查看原文，刷新后恢复屏蔽
2	不合规，严格屏蔽	永久屏蔽，客服无法查看原文

返回示例-合规：

{
    "msgId": "msg_001",
    "msgTag": 0
}

返回示例-不合规（宽松屏蔽）：

{
    "msgId": "msg_001",
    "msgTag": 1
}

返回示例-不合规（严格屏蔽）：

{
    "msgId": "msg_001",
    "msgTag": 2
}

● 异常处理

场景	智齿系统处理方式
接口超时（> 3 秒）	消息视为合规（msgTag=0），正常展示
接口不可达（DNS/网络故障）	消息视为合规（msgTag=0），正常展示
接口返回 HTTP 5xx	消息视为合规（msgTag=0），正常展示
返回 JSON 格式异常	消息视为合规（msgTag=0），正常展示
msgTag 返回非 0/1/2 的值	消息视为合规（msgTag=0），正常展示
返回体中无 msgTag 字段	消息视为合规（msgTag=0），正常展示

核心原则：合规检测的任何异常都不会阻塞消息流转，消息始终会正常入库和推送。

● 注意事项

1. 性能要求：接口需具备足够的并发处理能力。每条访客消息都会触发一次调用，超时上限为 3 秒，建议响应时间控制在 1 秒以内。
2. 检测准确性：检测结果的准确性由第三方接口负责，智齿系统不做二次校验。
3. 访客端不受影响：合规检测仅影响客服侧的消息展示，访客端始终正常显示所有消息。
4. 富文本责任边界：对象消息（msgType=5）的 content 为完整 JSON 字符串，可能包含图片、视频等多媒体元素。智齿将完整内容传递，不做拆分或预处理。检测结果以整条消息为单位，不支持对子元素分别标记。
5. 幂等性：同一 msgId 不会重复调用，但建议第三方接口做好幂等处理。