顶顶通呼叫中心中间件(mod_cti基于FreeSWITCH)-通话质检接口

实时质检

原理：通过ASR接口（依赖cti_asr接口），识别出实时识别说话内容，然后和关键词匹配执行挂机等动作。支持群集，配置和记录都存储到REDIS。

基于本接口开发的完整的实时质检系统请看这个文档 http://www.ddrj.com/qc/index.html

使用实例

<action application="export" data="nolocal:execute_on_answer_qc=cti_qc_session:bleg_group|common_group"/>
<action application="set" data="execute_on_answer_qc=cti_qc_session:aleg_group|common_group"/>
<action application="export" data="execute_on_answer_asr=cti_detect_speech_session:^^|127.0.0.1:9988|0|150|1000|3|0.2|5000|60000|''|''|0|''|1"/>
<action application="bridge" data="sofia/external/callin@180.76.224.191:35580"/>

通过http接口控制是否启动质检

http://ip/qc?caller_id_number=${caller_id_number}&destination_number=${destination_number}&channel=${url_encode(${channel_name})}

需要什么变量可以加到url,如果变量包含关键词需要 用url_encode 编码一下，例子： ${url_encode(${变量名})}

响应 {"header":{"local-qc-enable":"true","peer-qc-enable":"true","local-qc-keyword":"","peer-qc-keyword":""}}

  • local-qc-enable 本段是否启用实时质检，启用是字符串的”true”,不是布尔的true。

  • peer-qc-enable 对端是否启用实时质检

  • local-qc-keyword 本段质检关键词组，如果配置了多个关键词组用|分开。

  • peer-qc-keyword 对端质检关键词组，如果配置了多个关键词组用|分开。

image-20230814175623643

通过redis获取变量控制是否启动质检

redis 创建一个 key 名字：cti_qc_rule@域名 ,类型：hash， filed 是规则名， value为json格式的质检控制变量。

  {
	"set": {
		"qc-asr": "default",
		"qc-keyword": "keyword",
		"execute_on_answer_asr": "cti_detect_speech_session:^^|127.0.0.1:9988|0|150|1000|3|0.2|0|60000|''|'{\"group\":\"\\${qc-asr}\"}'|0|''|1",
		"execute_on_answer_qc": "cti_qc_session:\\${qc-keyword}"
	},
	"export": {
		"nolocal:qc-asr": "default",
		"nolocal:qc-keyword": "keyword",
		"nolocal:execute_on_answer_asr": "cti_detect_speech_session:^^|127.0.0.1:9988|0|150|1000|3|0.2|0|60000|''|'{\"group\":\"\\${qc-asr}\"}'|0|''|1",
		"nolocal:execute_on_answer_qc": "cti_qc_session:\\${qc-keyword}"
	}
}
  • set 控制本段质检参数
    • qc-asr 本段ASR配置
    • qc-keyword 本段质检关键词
    • execute_on_answer_asr 应答的时候启动ASR的参数
    • execute_on_answer_qc 应答的时候启动质检的参数
  • export 控制对端质检参数
    • nolocal:qc-asr 对端ASR配置
    • nolocal:qc-keyword 对端质检关键词
    • nolocal:execute_on_answer_asr 对端应答的时候启动ASR的参数
    • nolocal:execute_on_answer_qc 对端应答的时候启动质检的参数

使用质检规则的拨号方案例子

如果 变量 ${qc_rule_name} 不为空 就通过cti_variable 这个APP加载redis的qc配置规则。如果需要启用质检，只需要设置一个通道变量qc_rule_name为质检规则名。

cti_variable cti_qc_rule@${cti_domain} ${qc_rule_name}

image-20240712123556405

使用cti_transfer呼入转接实现呼入转接并且开启实时质检的例子

cti_transfer 用法文档请看 http://www.ddrj.com/callcenter/dialplan.html#%E5%91%BC%E5%85%A5%E8%BD%AC%E6%8E%A5

{
	"conditions": [
		[{
				"variable": "destination_number",
				"method": "prefix",
				"value": "5555"
			},
			{
				"variable": "caller_id_number",
				"method": "prefix",
				"value": "122"
			},
			{
				"variable": "network_addr",
				"method": "=",
				"value": "192.168.1.1"
			}
		]
	],
	"variables": {
		"qc-asr": "default",
		"qc-keyword": "keyword",
		"execute_on_answer_asr": "cti_detect_speech_session:^^|127.0.0.1:9988|0|150|1000|3|0.2|0|60000|''|'{\"group\":\"\\${qc-asr}\"}'|0|''|1",
		"execute_on_answer_qc": "cti_qc_session:\\${qc-keyword}"
	},
	"exports": {
	    "origination_nested_vars":"true",
		"absolute_codec_string": "pcma,pcmu,g729",
		"origination_caller_id_number": "前缀${caller_id_number:4}",
		"originate_timeout": "60",
		"nolocal:qc-asr": "default",
		"nolocal:qc-keyword": "keyword",
		"nolocal:execute_on_answer_asr": "cti_detect_speech_session:^^|127.0.0.1:9988|0|150|1000|3|0.2|0|60000|''|'{\"group\":\"\\${qc-asr}\"}'|0|''|1",
		"nolocal:execute_on_answer_qc": "cti_qc_session:\\${qc-keyword}"
	},
	"applications": [{
		"application": "bridge",
		"data": "sofia/external/前缀${destination_number:4}@demo.ddrj.com:11451"
	}],
	"priority":100
}
  • variables 设置呼入端的通道变量

  • exports 设置呼入和呼出2端的通道变量，如果只需要设置呼出端，不要设置呼入端就是变量前面加nolocal:

  • qc-asr 本段ASR配置

  • qc-keyword 本段质检关键词
  • absolute_codec_string 转接用的编码
  • origination_caller_id_number 转接主叫改写
  • originate_timeout 转接呼叫超时
  • nolocal:qc-asr 对端ASR配置
  • nolocal:qc-keyword 对端质检关键词

  • 改写规则说明 前缀${通道变量名字:去除前面几位}

  • priority 规则优先级，如果有多个规则，按优先级匹配

redis 配置说明

cti_rt_call_qc_keyword 和cti_rt_call_qc_keyword@domain[哈希表] 配置实时质检关键词和对应的动作，关键词支持正则表达式。

cti_rt_call_qc_keyword和cti_rt_call_qc_keyword@domain的区别，cti_rt_call_qc_keyword@domain指定的domain的fs才加载，cti_rt_call_qc_keyword连接这个redis的所有fs都会加载用于群集模式。

  1. key 组名

  2. value 具体关键词JSON格式

      {
      	"脏话": {
      		"keyword": ["他妈的", "去死吧","regex:.*操.*妈.*"],
      		"command": "uuid_kill",
      		"params": "",
              "level":0,
      	},
      	"自定义分类": {
      		"keyword": ["公账", "高新"],
      		"command": "uuid_sendmessage",
      		"params": "",
              "level":0 
    }
      }
    • keyword 关键词列表，如果正则表达式用前缀“regex:”。
    • command 匹配到关键词执行的API，可以执行挂机，发送通知等命令。
    • params API参数，参数前面会自动加上UUID。
    • level: 告警等级

cti_rt_call_qc_keyword 改变通知

cti_rt_call_qc_keyword 改变PUBLISH 通知到config@all [通道] ，cti_rt_call_qc_keyword@domain改变PUBLISH 通知到config@domain[通道]

{
	"type":"config_change",
	"table":"cti_rt_call_qc_keyword",
	"key":"t1"
}

qc 通知

配置cti.json


"qc": {
  "log": true,   
  "database":{
  "table":"qc_record"
  },
  "redis": {
    "qc_asr": {
      "channel": "cti_qc",
      "list": "cti_rt_call_qc_asr"
    },

    "qc_hit": {
      "channel": "cti_qc",
      "list": "cti_rt_call_qc_hit"
    },

    "qc_start": {
      "channel": "cti_qc",
      "list": "cti_rt_call_qc_start",
      "variables": [ "caller_id_number", "callee_id_number", "direction" ]
    },

    "qc_stop": {
      "channel": "cti_qc",
      "list": "cti_rt_call_qc_stop"
    }
  }
}
  • log 是否输出qc记录日志
  • channel qc记录推送redis的channels名字
  • list qc记录写入redis的list名字

qc_start 启动通知

{
	"datetime": "2021-07-21 20:58:58",
	"domian": "my",
	"type": "qc_start",
	"groupnames": ["bleg"],
	"uuid": "f26805ca-7069-4a28-bde0-6bcbd32ad570",
	"call_uuid": "71bda206-0cbb-4ea0-b975-64a995b7b59e",
	"caller_id_number": "123",
	"callee_id_number": "123",
	"direction": "outbound"
}
  • groupnames start_qcc 使用的关键词组
  • uuid 通道的uuid
  • call_uuid call_uuid 如果有通话的双方，2边会使用一样的call_uuid,估计是主叫的uuid

qc_stop 停止通知

{
	"uuid": "f26805ca-7069-4a28-bde0-6bcbd32ad570",
	"call_uuid": "71bda206-0cbb-4ea0-b975-64a995b7b59e",
	"domian": "my",
	"type": "qc_stop",
	"datetime": "2021-07-21 20:59:07"
}

qc_asr asrt通知

默认一句话说完了才发送通知，如果需要通知识别的中间件结果 需要设置通道变量 qc_push_intermediate_result=true 就可以发送实时的识别结果，注意：中间件结果只支持通道到redis的channel。

{

    "uuid": "71bda206-0cbb-4ea0-b975-64a995b7b59e",
    "type": "qc_asr",
    "domian": "my",
    "datetime": "2021-07-21 20:58:58",
    "bridge_uuid": "f26805ca-7069-4a28-bde0-6bcbd32ad570",
    "call_uuid": "71bda206-0cbb-4ea0-b975-64a995b7b59e"
    "speak_start": "说话开始时间，接通开始计算单位毫秒",
    "speak_stop": "说话停止时间，接通开始计算单位毫秒",
    "text": "识别到的句子,第一个字符F表示句子，E表示错误",
    "domian":"cti.conf.xlm配置的domain,用于分别来自那台fs",
}
  • bridge_uuid 桥接的通道ID（通话的对方）
  • datetime 开始说话的事件

qc_hit 匹配关键词通知

{
       "uuid":"uuid",
   　"type": "qc_hit",
    "datetime": "2021-07-21 20:59:04",
    "bridge_uuid": "f26805ca-7069-4a28-bde0-6bcbd32ad570",
    "call_uuid": "71bda206-0cbb-4ea0-b975-64a995b7b59e",
    "speak_start": "说话开始时间，接通开始计算单位毫秒",
    "speak_stop": "说话停止时间，接通开始计算单位毫秒",
    "text": "识别到的句子,第一个字符F表示句子，E表示错误,S表示没识别到说话停止就挂掉",
    "domian":"cti.conf.xlm配置的domain,用于分别来自那台fs",
    "group":"组名，cti_rt_call_qc_keyword的KEY",
       "category":"keyword所属的分类",
    "keyword": "关键词",
    "match":"keyword和text的匹配信息",
    "command":"执行命令信息",
    "level":1
}

质检结果写入数据库

cti.json 配置文件里面 qc.database.table 配置上记录的表名，就会把质检结果记录到数据库。

表结构如下

CREATE TABLE `qc_record` (
	`uuid` VARCHAR(50) NOT NULL,
	`datetime` DATETIME NULL DEFAULT CURRENT_TIMESTAMP,
	`hit` JSON NULL DEFAULT NULL,
	`speak` JSON NULL DEFAULT NULL,
	`level` TINYINT(3) NULL DEFAULT NULL,
	PRIMARY KEY (`uuid`) USING BTREE
)

  • uuid通话的callid

  • hit 命中关键词的记录

    [{
    	"hit": "银行卡",
    	"time": 1704603297108,
    	"group": "keywords",
    	"level": 1,
    	"method": "strstr",
    	"command": "uuid_broadcast",
    	"keyword": "银行卡",
    	"category": "敏感词"
    }, {
    	"hit": "公安局",
    	"time": 1704603301648,
    	"group": "keywords",
    	"level": 1,
    	"method": "strstr",
    	"command": "uuid_broadcast",
    	"keyword": "公安局",
    	"category": "敏感词"
    }]
    • hit 命中的文本
    • time 命中文本说话开始时间
    • level 告警等级
    • method 关键词匹配方法
    • command 执行的命令
    • keyword 关键词
    • category 词库名
    • group 词库组

  • speak 语音识别的记录

    [{
    	"text": "你好。",
    	"time": 1704603292688,
    	"duration": 2180
    }, {
    	"text": "你有银行卡吗。",
    	"time": 1704603297108,
    	"duration": 2340
    }, {
    	"text": "福州市公安局。",
    	"time": 1704603301648,
    	"duration": 2860
    }]
    • time 说话开始时间，unix时间戳，微妙。
    • duration 说话持续时间

  • level 最大警告等级

FreeSWITCH 接口说明

APP cti_start_qc(group) 开始实时通话质检

  • group rt_call_qc_keyword配置的组，多个组用|隔开，使用那些组中的关键词。

API uuid_cti_start_qc uuid group 开始实时通话质检

参数和start_qc一样。

API uuid_cti_stop_ac uuid 停止实时通话质检

API cti show qc_all 显示qc已经加载的关键词组