机器人知识库编辑表达式·一洽客服系统API
目录
1. 表达式简介
2. 表达式规则
3. 系统变量
4. 操作表达式
5. 数据表达式
6. 逻辑表达式
1.表达式简介
在机器人服务客户时，知识的答案往往会因为访客身份的不同，语境、地区、业务的不同需要返回针对性的答案，通过此文档您可实现在知识答案中动态的返回不同的内容，例如：针对性的称呼 李先生来咨询时为：您好，李先生 刘小姐来咨询时为：您好，刘小姐。同时通过此文档您可在知识中对接企业的业务系统，比如访客咨询”我的剩余积分"，通过集成企业的积分系统返回给访客详细的积分数据。通过使用一洽知识库表达式，企业不需要AI工程师参与深度定制即可实现较复杂的业务集成。
2.表达式规则
从表达式的场景和用法，可将表达式分为三类，操作表达式、数据表达式、逻辑表达式
操作表达式：通过植入表达式可在知识的答案中个性化定制业务操作，比如：转人工对话、转留言、结束对话
数据表达式：通过植入数据表达式，可在知识的答案中动态使用企业的业务数据，比如会员积分数据、会员订单列表、热门产品列表等等
逻辑表达式：通过植入逻辑表达式，可在知识的答案中根据实时的一些状态返回不同的内容，比如：客服在线返回转人工的提示，客服离线则返回客服不在线的提示。
3.系统变量
在知识库中可使用系统变量实现答案指定元素的动态反馈，例如使用${robotInfo.nickName}动态使用当前服务器机器人的名称。系统变量可使用在知识库答案中的任何位置，包括上面章节提到的表达式中。
系统变量组成规则
${variableScope.variableName} VariableScope:变量的作用域范围。variableName变量名称。
系统变量支持列表
| variableScope | variableName | 表达式 | 描述 |
|---|---|---|---|
| robotInfo | nickName | ${robotInfo.nickName} | 当前服务器机器人的昵称 |
| systemInfo | dateutc | ${systemInfo.dateutc[0-9_]} | 指定时区的日期。根据东西时区的tuc数值，将负号和标点符号替换为下划线后为指定时区的时间，比如${systemInfo.dateutc_12}代表西十二区时间，${systemInfo.dateutc8}代表东八区的时间，时区请参考：https://www.beijing-time.org/shiqu/， 日期格式： yyyy-MM-dd 例如：2020-10-01 |
| systemInfo | timeutc | ${systemInfo.timeutc[0-9_]} | 指定时区的时间。根据东西时区的utc数值，将负号和标点符号替换为下划线后为指定时区的时间，比如${systemInfo.timeutc_12}代表西十二区时间，${systemInfo.timeutc8}代表东八区的时间，时区请参考：https://www.beijing-time.org/shiqu/， 时间格式： yyyy-MM-dd HH:mm:ss 例如：2020-10-01 12:00:00 |
| chatInfo | lan | ${chatInfo.lan} | 当前访客此次来访的语言，语言代码请参照：http://www.lingoes.cn/zh/translator/langcode.htm |
| chatInfo | echatTag | ${chatInfo.echatTag} | 当前访客此次请求对话的业务标签。 |
| chatInfo | lastChatTime | ${chatInfo.lastChatTime} | 上次会话时间,时间格式yyyy-MM-dd HH:mm:ss |
| chatInfo | chatTimes | ${chatInfo.chatTimes} | 本次会话是当前访客第几次会话。 |
| chatInfo | visitTimes | ${chatInfo.visitTimes} | 本次来访是当前访客第几次来访。 |
| chatInfo | myData | ${chatInfo.myData} | 访客接入对话时，企业设置的业务数据（任意值，最大长度500字符）。 |
| chatInfo | keyword | ${chatInfo.echatTag} | 访客来访渠道为搜索引擎时的搜索关键字。 |
| routeInfo | routeId | ${routeInfo.routeId} | 本次会话所选定的路由ID。 |
| routeInfo | routeName | ${routeInfo.routeName} | 本次会话所选定的路由名称。 |
| routeInfo | routeStatus | ${routeInfo.routeStatus} | 本次会话所选定路由，在访客咨询问题时客服接待状态 1：在线 2：离线。 |
| userInfo | vipId | ${userInfo.vipId} | 访客所在渠道的唯一ID，如：微信渠道的openId，会员的uid |
| userInfo | vipType | ${userInfo.vipType} | 访客类型 0：web匿名 1：会员 2：sdk匿名 4：微信访客 6：小程序访客 7：新浪微博访客 |
| userInfo | visitorId | ${userInfo.visitorId} | 访客的唯一ID 例如：web123，wechat23421 |
| userInfo | visitorName | ${userInfo.visitorName} | 当前咨询访客的名字 |
| locationInfo | ip | ${locationInfo.ip} | 访客的来源ip（非web渠道访问没有来源ip） |
| locationInfo | country | ${locationInfo.country} | 访客所在国家（ip解析或者微信等渠道的个人信息获得） |
| locationInfo | province | ${locationInfo.province} | 访客所在省份（ip解析或者微信等渠道的个人信息获得） |
| locationInfo | city | ${locationInfo.city} | 访客所在城市（ip解析或者微信等渠道的个人信息获得） |
4.操作表达式
[[#${function}:${params}]]以两个中括号打头追加#${function}:后系统会自动识别到表达式，同时将表达式替换为指定的内容或者添加指定的事件。
function:系统支持的表达式方法，比如：转人工对话、结束对话、获取数据、转留言
params:执行当前表达式方法传递的参数
表达式列表
| function | param格式 | 表达式示例 | 解析阶段 | 解释 |
|---|---|---|---|---|
| toChat | string | [[#toChat:转接人工]] | 答案返回后 | 点击param内容后可进行抓人工请求。 |
例如：结束对话表达式，在系统识别到此表达式后系统会在机器人的答案中直接提供转人工操作。
表达式：[[#toChat:点击转接客服]]
效果：
5.数据表达式
数据表达式
((#${function}:${params}))以两个小括号打头追加#${function}:后系统会自动识别到表达式，同时将请求回来的数据内容。
function:系统支持的表达式方法，比如：获取业务数据
params:执行当前表达式方法传递的参数
表达式列表
| function | param格式 | 表达式示例 | 解析阶段 | 解释 |
|---|---|---|---|---|
| queryData | url | ((#queryData:url)) |
答案返回前 | 在答案返回前会向此表达式配置的url get数据将返回的数据追加到表达式出现在的答案中的位置 |
get参数追加签名
请求地址：
${url}[?|&]nonce=${nonce}×tamp=${timestamp}&signature=${signature}
参数说明
| 参数 | 描述 |
|---|---|
| signature | 一洽加密签名，signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。 |
| timestamp | 时间戳 |
| nonce | 随机数 |
signature生成过程如下：
1）将token、timestamp、nonce三个参数进行字典序排序 2）将三个参数字符串拼接成一个字符串进行sha1加密 3）一洽按照如上方法对字符串加密后与参数中的signature对比，如果一致则认为是合法的请求
详细签名生成方法请参看 accessToken生成规则中的签名生成规则。
数据返回说明
请求超时时间：5000ms
返回格式为json数据
| 参数 | 类型 | 说明 |
|---|---|---|
| type | enum | 返回的业务数据类型。 text:将返回的内容直接替换掉表达式 |
| content | string | 数据内容，根据type的类型对content进行指定规则的使用 |
例如：获取会员数据，将获取回来的会员数据融入到答案中返回给访客
表达式：((#queryData:https://crm.echatsoft.com/getUserInfo?userId=${userInfo.visitorId}&lan=${chatInfo.lan}))
返回的数据：
{
"type":"text",
"content":"用户名：一洽客服
加入日期：2015-01-01
剩余积分：1818
历史兑换积分：6868"
}
知识库编辑：
访客查看答案效果：
6.逻辑表达式
{{#${logic}:${content}}}以两个大括号打头追加#${logic}:后系统会自动识别到表达式，同时根据表达式的逻辑结果真/假动态显示答案，即在当前条件为真时，答案中将包含${content}。
logic:系统支持的逻辑判断，比如：客服在线、客服离线、会员访客、匿名访客、
content:逻辑为真是显示在答案中的内容
表达式列表
| logic | 解析阶段 | 解释 |
|---|---|---|
| staffOnline | 答案返回前 | 当前请求业务线的客服状态为在线 |
| staffOffline | 答案返回前 | 当前请求业务线的客服状态为离线 |
| vipUser | 答案返回前 | 当前访客是会员 |
| anonymityUser | 答案返回前 | 当前访客是匿名 |
例如：客服在线则提示转人工、客服不在线则提示客服服务时间
表达式：
{{#staffOnline:您好，当前客服在线，您可[[#toChat:点击转接客服]]}}
{{#staffOffline:您好，当前客服不在线，请在周一到周五的9:00-18:00联系客服}}
知识库编辑：
客服在线访客查看答案效果:
客服不在线访客查看答案效果:
