旧版 Dialogflow CX Messenger 集成 为您的代理提供可自定义的聊天对话框 可嵌入到您网站的内容中 聊天对话框以最终用户可以打开和关闭的对话窗口形式实现。打开时,聊天对话框会显示在屏幕右下方的内容上方。
迁移到最新版本的 Dialogflow CX Messenger
最新版本的 Dialogflow CX Messenger 提供身份验证功能,可控制代理查询访问权限,并提供更多界面配置选项。建议旧版的所有用户迁移到新版。
如果您在 2023 年 8 月 29 日之前启用了 Dialogflow CX Messenger 集成, 您可能使用的是旧版本。 如需确定您是否使用的是旧版,请检查您网站上嵌入的 Messenger 聊天室 HTML 代码。如果您看到以下脚本,则表示您使用的是旧版:
https://www.gstatic.com/dialogflow-console/fast/messenger-cx/bootstrap.js?v=1
如需迁移到新版本,请执行以下操作:
- 从您的网站中删除所有 HTML、CSS 和 JavaScript 聊天机器人代码。
- 请按照 最新的 Dialogflow CX Messenger 集成。
HTML 自定义
您可以自定义聊天对话框显示方式和行为方式的各个方面。df-messenger
HTML 元素具有以下特性 (Attribute):
特性 | 输入政策 | 值 |
---|---|---|
agent-id |
必填 | 与客服人员关联的客服人员 ID。这是用代理 ID 预填充的。 |
chat-icon |
可选 | 用于聊天对话框打开按钮的图标。对话式客服 (Dialogflow CX) 图标是默认的图标。此字段必须为公开网址。图标大小应为 36 x 36 像素。 |
chat-title |
必需 | 显示在聊天对话框顶部的标题。这是用代理的名称预填充的。 |
df-cx |
必需 | 表示与 CX 代理互动。使用“true”作为值。 |
expand |
可选 | 布尔值特性,用于将聊天对话框设置为在页面加载时打开。默认情况下,聊天对话框在页面加载时处于关闭状态。 |
intent |
可选 | 在聊天对话框打开时调用的自定义事件。您可以使用将针对此事件调用并生成第一个客服消息的事件处理程序。 |
language-code |
必填 | 第一个意图的默认语言代码。这是用代理的默认语言预填充的。 |
location |
必需 | 代理的区域。 |
session-id |
可选 | 会话 ID。如果未提供,则集成会为每个聊天对话框生成唯一 ID。 |
user-id |
可选 | 可用于跨会话跟踪用户。您可以通过检测意图请求中的 queryParams.payload.userId 字段将值传递给对话式 AI 客服 (Dialogflow CX),然后对话式 AI 客服 (Dialogflow CX) 通过 WebhookRequest.payload.userId 字段向您提供此值。 |
wait-open |
可选 | 布尔值属性,用于将 intent 属性中定义的自定义事件延迟到对话框实际打开之后再进行。 |
CSS 自定义
您可以通过设置 CSS 变量来自定义聊天对话框的样式。
可提供以下 CSS 变量:
CSS 变量 | 受影响的属性 (Property) |
---|---|
df-messenger-bot-message |
代理消息的气泡背景颜色。 |
df-messenger-button-titlebar-color |
聊天对话框的浮动按钮和标题栏的颜色。 |
df-messenger-button-titlebar-font-color |
标题栏中标题的字体颜色。 |
df-messenger-chat-background-color |
聊天对话框的背景颜色。 |
df-messenger-font-color |
消息的字体颜色。 |
df-messenger-input-box-color |
文本输入框的背景颜色。 |
df-messenger-input-font-color |
文本输入框的字体颜色。 |
df-messenger-input-placeholder-font-color |
文本输入框中占位符文本的字体颜色。 |
df-messenger-minimized-chat-close-icon-color |
关闭的聊天视图中关闭图标的颜色。 |
df-messenger-send-icon |
文本输入框中发送图标的颜色。 |
df-messenger-user-message |
用户消息的气泡背景颜色。 |
示例代码:
<style>
df-messenger {
--df-messenger-bot-message: #878fac;
--df-messenger-button-titlebar-color: #df9b56;
--df-messenger-chat-background-color: #fafafa;
--df-messenger-font-color: white;
--df-messenger-send-icon: #878fac;
--df-messenger-user-message: #479b3d;
}
</style>
以上设置的显示效果如下:
JavaScript 事件
Dialogflow Messenger 会触发各种事件,您可以为这些事件创建事件监听器。
这些事件的事件目标是 df-messenger
元素。
要为 df-messenger
元素添加事件监听器,请添加以下 JavaScript 代码,其中 event-type
是下述事件名称之一:
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
系统支持以下事件类型:
df-accordion-clicked
当用户点击折叠式元素时会发生此事件。事件结构如下所示:
element: {
title: string,
subtitle: string,
image: {
src: {rawUrl: string}
},
text: string
}
df-button-clicked
当用户点击按钮元素时会发生此事件。 事件结构如下所示:
element: {
icon: {
type: string,
color: string
},
text: string,
link: string,
event: EventInput,
payload: {}
}
df-chip-clicked
当用户选择建议内容信息卡时会发生此事件。事件结构如下所示:
query: string // Text of the suggestion chip that was selected.
df-info-card-clicked
当最终用户点击标题栏中的信息项时,会发生此事件。事件结构如下所示:
element: {
title: string,
image: {
src: {rawUrl: string}
},
actionLink: string
}
df-list-element-clicked
当用户点击列表中的项时,会发生此事件。 事件结构如下所示:
element: {
title: string,
subtitle: string,
image: {
src: {rawUrl}
},
event: {
name: string
},
payload: {}
}
df-messenger-error
当 Dialogflow API 发送错误状态代码时,会发生此事件。 事件结构如下所示:
error: {
"error": {
"code": <error_code>,
"message": <error_message>,
"status": <error_status>
}
}
df-messenger-loaded
当 df-messenger
元素已完全加载并初始化时会触发此事件。
df-request-sent
当对 Dialogflow API 发出请求时,会发生此事件。
此事件以及 df-response-received
可用于监控请求延迟时间。事件结构如下所示:
requestBody: {
"queryParams": {
object(QueryParameters)
},
"queryInput": {
object(QueryInput)
},
"inputAudio": string
}
df-response-received
当从 Dialogflow API 收到响应时,会发生此事件。 事件结构如下所示:
response: detectIntentResponse
df-user-input-entered
当最终用户输入查询时会发生此事件。 事件结构如下所示:
input: string // Text entered by user
JavaScript 函数
df-messenger
元素提供了您可以调用来影响其行为的函数。
renderCustomText
此函数会呈现一条简单的文本消息, 就像来自对话代理 (Dialogflow CX) 一样简单文本响应。
例如:
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.renderCustomText('Custom text');
renderCustomCard
此函数会呈现自定义卡片 就像来自对话代理 (Dialogflow CX) fulfillment 一样。 自定义载荷响应的格式已在 Fulfillment 部分中定义。
例如:
const dfMessenger = document.querySelector('df-messenger');
const payload = [
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}];
dfMessenger.renderCustomCard(payload);
showMinChat
此函数会显示消息列表的最小版本。
例如:
const dfMessenger = document.querySelector('df-messenger');
dfMessenger.showMinChat();
Fulfillment
创建 Fulfillment 时,您可以创建文本响应和自定义载荷。文本响应用于基本代理响应,自定义载荷用于富响应。适用于所有响应类型的自定义载荷格式具有以下基本结构:
{
"richContent": [
[
{
"type": "type-id",
...
},
{
"type": "type-id",
...
}
],
[
{
"type": "type-id",
...
},
{
"type": "type-id",
...
}
]
]
}
请注意,richContent
值可以为一个外部数组和多个内部数组。内部数组中的响应会绑定到单个可视化卡片中。
当外部数组包含多个内部数组时,会显示多个卡片,每个卡片对应一个内部数组。
其余子部分介绍了您可以为自定义载荷配置的各类型响应。
信息响应类型
信息响应类型是用户可点击或轻触的简单标题卡片。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“信息” |
title |
字符串 | 卡片标题 |
subtitle |
字符串 | 卡片副标题 |
image |
对象 | 图片 |
image.src |
对象 | 图片来源 |
image.src.rawUrl |
字符串 | 图片的公开网址 |
actionLink |
字符串 | 点击卡片后要转到的网址 |
例如:
{
"richContent": [
[
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}
]
]
}
说明响应类型
说明响应类型是可以包含多行文本的信息卡片。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“说明” |
title |
字符串 | 卡片标题 |
text |
数组<string> | 每个字符串都在新行中呈现的字符串数组 |
例如:
{
"richContent": [
[
{
"type": "description",
"title": "Description title",
"text": [
"This is text line 1.",
"This is text line 2."
]
}
]
]
}
图片响应类型
图片响应类型是用户可以点击或轻触的图片卡片。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“图片” |
rawUrl |
字符串 | 图片的公开网址 |
accessibilityText |
字符串 | 图片的替代文本 |
例如:
{
"richContent": [
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
]
}
按钮响应类型
按钮响应类型是一个带有图标的小按钮,用户可以点击或轻触该按钮。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“按钮” |
icon |
对象 | 按钮的图标 |
icon.type |
字符串 | Material 图标库中的图标。默认图标是箭头 |
icon.color |
字符串 | 颜色的十六进制代码 |
text |
字符串 | 按钮文字 |
link |
字符串 | 点击按钮后要转到的网址 |
event |
对象 | 点击按钮时会触发的对话式客服 (Dialogflow CX) 事件。 |
例如:
{
"richContent": [
[
{
"type": "button",
"icon": {
"type": "chevron_right",
"color": "#FF9800"
},
"text": "Button text",
"link": "https://example.com",
"event": {
"name": ""
}
}
]
]
}
列表响应类型
列表响应类型是一个具有多个选项的卡片,用户可以从这些选项中进行选择。
响应包含 list
和 divider
响应类型的数组。下表介绍了 list
类型:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“列表” |
title |
字符串 | 选项标题 |
subtitle |
字符串 | 选项副标题 |
event |
对象 | 用户点击选项时触发的对话代理 (Dialogflow CX) 事件。 |
下表介绍了 divider
类型:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“分隔器” |
例如:
{
"richContent": [
[
{
"type": "list",
"title": "List item 1 title",
"subtitle": "List item 1 subtitle",
"event": {
"name": ""
}
},
{
"type": "divider"
},
{
"type": "list",
"title": "List item 2 title",
"subtitle": "List item 2 subtitle",
"event": {
"name": ""
}
}
]
]
}
折叠式响应类型
折叠式响应类型是一个小卡片,用户可以点击或轻触该卡片来展开和显示更多文本。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“折叠式” |
title |
字符串 | 折叠式标题 |
subtitle |
字符串 | 折叠式副标题 |
image |
对象 | 图片 |
image.src |
对象 | 图片来源 |
image.src.rawUrl |
字符串 | 图片的公开网址 |
text |
字符串 | 折叠式文本 |
例如:
{
"richContent": [
[
{
"type": "accordion",
"title": "Accordion title",
"subtitle": "Accordion subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"text": "Accordion text"
}
]
]
}
建议内容信息卡响应类型
建议内容信息卡响应类型向最终用户提供可点击的建议内容信息卡列表。
下表介绍了各个字段:
名称 | 类型 | 说明 |
---|---|---|
type |
字符串 | 响应类型:“信息卡” |
options |
数组<object> | 选项对象的数组 |
options[].text |
字符串 | 选项文本 |
options[].image |
对象 | 选项图片 |
options[].image.src |
对象 | 选项图片来源 |
options[].image.src.rawUrl |
字符串 | 选项图片的公开网址 |
options[].link |
字符串 | 选项链接 |
例如:
{
"richContent": [
[
{
"type": "chips",
"options": [
{
"text": "Chip 1",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"link": "https://example.com"
},
{
"text": "Chip 2",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"link": "https://example.com"
}
]
}
]
]
}
合并响应类型
Dialogflow CX Messenger 的各个富消息元素 可用于构建符合您需求的自定义卡片。 下面是一个使用上述部分元素的示例:
{
"richContent": [
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Conversational Agents (Dialogflow CX) across platforms"
},
{
"type": "info",
"title": "Conversational Agents (Dialogflow CX)",
"subtitle": "Build natural and rich conversational experiences",
"actionLink": "https://cloud.google.com/dialogflow/docs"
},
{
"type": "chips",
"options": [
{
"text": "Case Studies",
"link": "https://cloud.google.com/dialogflow/case-studies"
},
{
"text": "Docs",
"link": "https://cloud.google.com/dialogflow/docs"
}
]
}
]
]
}
调试
如需在本地使用 Dialogflow CX Messenger 测试您的客服,请执行以下操作:
- 按照 HTML 自定义部分。
- 使用特定端口启动该页面的本地 HTTP 服务器。
- 通过
http://localhost:port_number
访问该页面。