Rasa Webchat 💬

一个聊天小部件，用于将使用 Rasa 或 Botfront 构建的虚拟助手部署到任何网站上。

⚠️ Rasa Webchat 1.0.1 版本专为 Rasa 2.3.x 和 2.4.x 版本设计。对于其他 Rasa 版本，请使用 1.0.0 版本。

功能

• 文本消息
• 快速回复
• 图片
• 轮播
• Markdown 支持
• 持久会话
• 键入提示
• 智能消息延迟
• 可轻松通过 <script> 标签或作为 React 组件引入

🔥 推广：来看看我们另一个超酷的开源项目

使用方法

在 <script> 标签中

在你的 <body/> 中：

<script>!(function () {
  let e = document.createElement("script"),
    t = document.head || document.getElementsByTagName("head")[0];
  (e.src =
    "https://cdn.jsdelivr.net/npm/rasa-webchat@1.x.x/lib/index.js"),
    // 将 1.x.x 替换为你想要的版本
    (e.async = !0),
    (e.onload = () => {
      window.WebChat.default(
        {
          customData: { language: "en" },
          socketUrl: "https://bf-botfront.development.agents.botfront.cloud",
          // 在此处添加其他属性
        },
        null
      );
    }),
    t.insertBefore(e, t.firstChild);
})();
</script>

⚠️ 我们建议添加版本标签，以避免重大版本更新带来的破坏性变化，例如对于 1.0.0 版本：https://cdn.jsdelivr.net/npm/rasa-webchat@1.0.0/lib/index.js。不过，这不适用于 1.0.0 以下的版本。如果不指定版本，系统将自动加载最新可用的 Rasa Webchat 版本。

关于图片：width 和 height 定义了消息中图片裁剪缩放后的像素尺寸。如果未设置，则图片将根据容器的最大宽度进行缩放。

作为 React 组件

安装 npm 包：

npm install rasa-webchat

然后：

import Widget from 'rasa-webchat';

function CustomWidget = () => {
  return (
    <Widget
      initPayload={"/get_started"}
      socketUrl={"http://localhost:5500"}
      socketPath={"/socket.io/"}
      customData={{"language": "en"}} // 任意自定义数据。尽量保持简洁，因为这些数据会被添加到 Socket 连接中
      title={"标题"}
    />
  )
}

• 如果你不想显示启动器，请确保将 embedded 属性设置为 true。

参数

属性 / 参数	默认值	描述
initPayload	null	会话开始时发送给 Rasa 的负载
socketUrl	null	Socket URL
socketPath	null	关闭聊天窗口
customData	null	随 Socket 一起发送的任意对象。如果与 Botfront 一起使用，必须包含语言信息（例如 {"language": "en"}）
docViewer	false	如果将此属性添加到组件或初始化脚本中，设置为 docViewer=true，则会将接收到的消息中的链接视为文档链接（如 .pdf、.doc、.xlsx 等），并通过 https://docs.google.com/viewer 服务在弹出窗口中打开它们。
title	'Welcome'	小部件头部显示的标题
subtitle	null	小部件头部标题下方显示的副标题
inputTextFieldHint	"Type a message"	用户消息输入框的占位符
hideWhenNotConnected	true	如果设置为 true，当与 Socket 的连接断开时，小部件将隐藏。
connectOn	"mount"	此属性允许您选择小部件何时尝试连接到服务器。默认情况下，它会在挂载时立即尝试连接。如果您选择 connectOn='open'，则仅在打开小部件时才会尝试连接。该属性只能取值为 mount 或 open。
onSocketEvent	null	在特定的 Socket 事件发生时调用自定义代码
embedded	false	如果希望将小部件嵌入网页中，请将其设置为 true。此时小部件将始终处于打开状态，并且会立即触发 initPayload。
showFullScreenButton	false	显示全屏切换按钮
displayUnreadCount	false	当小部件关闭时，在启动器上显示的图片路径
showMessageDate	false	显示消息日期。可以通过函数覆盖：(timestamp, message) => return 'my custom date'。
customMessageDelay	见下文	此属性是一个函数，接收消息字符串作为参数。每次收到消息时都会调用该函数，并将返回的毫秒数作为延迟时间，在显示新消息之前等待。
params	见下文	主要用于自定义图片大小，也可用于更改存储选项。
storage	"local"	⚠️ 这不是一个属性，必须通过上述 params 对象传递。 指定会话状态在浏览器中的存储位置。“session”表示将状态存储在会话存储中。会话存储在页面重新加载时仍然存在，但在浏览器或标签页关闭后，或者调用 sessionStorage.clear() 时会被清除。“local”表示将状态存储在本地存储中。本地存储在浏览器关闭后仍然存在，但在清除浏览器 Cookie 或调用 localStorage.clear() 时会被清除。
customComponent	null	用于自定义响应的自定义组件。例如：customComponent={ (messageData) => (<div>自定义 React 组件</div>)}。请注意，这仅适用于从 React 应用程序调用 Webchat 的情况，因为无法仅使用纯 JavaScript 编写组件。
onWidgetEvent	{}	在特定的小部件事件上调用自定义代码（目前可用的事件包括 onChatOpen、onChatClose、onChatHidden），只需在 props 中相应对象属性上添加函数，即可使其对事件作出反应。

其他示例

customMessageDelay

(message) => {
    let delay = message.length * 30;
    if (delay > 2 * 1000) delay = 3 * 1000;
    if (delay < 400) delay = 1000;
    return delay;
}

onSocketEvent

onSocketEvent={{
  'bot_uttered': () => console.log('机器人说了一些话'),
  'connect': () => console.log('连接已建立'),
  'disconnect': () => doSomeCleanup(),
}}

params

params 属性仅允许指定自定义图片尺寸：

params={{
        images: {
          dims: {
            width: 300,
            height: 200
          }
        }
      }}

其他功能

工具提示

当小部件关闭时接收到的文本消息将以工具提示的形式显示。

页面加载时发送消息

在重新连接到现有聊天会话时，机器人将发送存储在由 NEXT_MESSAGE 常量指定的 localStorage 键中的消息。该消息应为字符串化的 JSON，包含一个描述消息内容的 message 属性，以及一个以毫秒为单位的 UNIX 时间戳 expiry 属性，表示在此时间之后不应再发送该消息。这在希望机器人能够引导用户浏览网站时非常有用。

从你的 React 应用程序发送负载

function myComponent() {
    const webchatRef = useRef(null);
    
    // 当你的应用中发生某些事情时触发
    function callback() {
        if (webchatRef.current && webchatRef.current.sendMessage) {
            webchatRef.current.sendMessage('/myIntent{"entityName":"value"}');
        }
    }
    
    return <RasaWebchat
        ref={webchatRef}
    />;
}

负载可以是用户通常会发送的任何消息，但如果你想强制执行某个意图并可能包含一些实体，可以使用以下格式： /myIntent{"entity1":"value1","entity2":"value2"}

后端

该小部件可以与任何后端配合使用，但主要设计用于与 Rasa 或 Botfront 配合使用。

Rasa

使用 socketio 通道：请参阅 Rasa 文档中的说明

如果你想在 Rasa 中处理 customData，则需要 创建一个新的通道。可以将通道 rasa_core.channels.socketio 用作新通道的模板。在此通道中，可以通过 data['customData'] 获取 customData。然后你可以修改 sender_id，将 customData 保存到数据库，填充槽位，或者根据你的额外数据进行其他操作。

Botfront

Rasa Webchat 由 Botfront 团队开发，并且与 Botfront 配合使用。如果你的机器人是多语言的，请确保在 customData 属性中指定当前语言。例如：customData={{language: 'en'}}。更多详细信息请参阅 Botfront 文档。

样式

从版本 0.8 开始，我们对所有 CSS 类名添加了前缀。如果你已经为小部件设置了样式，只需在你修改过的所有类名前加上 rw- 即可。

层次结构如下：

.rw-conversation-container
  |-- .rw-header
        |-- .rw-title
        |-- .rw-close-function
        |-- .rw-loading
  |-- .rw-messages-container
        |-- .rw-message
              |-- .rw-client
              |-- .rw-response
        |-- .rw-replies
              |-- .rw-reply
              |-- .rw-response
        |-- .rw-snippet
              |-- .rw-snippet-title
              |-- .rw-snippet-details
              |-- .rw-link
        |-- .rw-imageFrame
        |-- .rw-videoFrame
  |-- .rw-sender
        |-- .rw-new-message
        |-- .rw-send

类名	描述
.rw-widget-container	默认版本中包含聊天框的 div
.rw-widget-embedded	嵌入式聊天框的 div（使用 embedded prop）
.rw-full-screen	全屏聊天框的 div（使用 fullScreenMode prop）
.rw-conversation-container	包含头部、消息容器和发送区域的父级 div
.rw-messages-container	消息显示的中心区域
.rw-sender	底部区域的 div，用于提示用户输入
.rw-new-message	发送区域中的文本输入元素
.rw-send	发送区域中的发送图标元素
.rw-header	包含聊天框头部的顶部区域 div
.rw-title	头部的标题元素
.rw-close-button	头部的关闭图标
.rw-loading	头部的加载状态元素
.rw-message	存放客户消息和回复消息的方框
.rw-replies	提供快速回复选项的区域
.rw-snippet	用于描述链接的组件
.rw-imageFrame	用于发送图片的容器
.rw-videoFrame	用于发送视频的容器

贡献者

@PHLF @znat @TheoTomalty @Hub4IT @dliuproduction @MatthieuJnon @mofortin @GuillaumeTech

许可证

版权所有 © 2021 Dialogue Technologies Inc.

根据 Apache License, Version 2.0（“许可证”）授权； 除非符合许可证的规定，否则不得使用此文件。 你可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据“现状”分发的软件， 不提供任何形式的保证或条件。 有关权限和限制的具体规定，请参阅许可证。（C）2021 Dialogue Technologies Inc. 版权所有。

Rasa Webchat 快速上手指南

Rasa Webchat 是一个轻量级的聊天窗口组件，用于在任何网站上部署由 Rasa 或 Botfront 构建的虚拟助手。它支持文本、快速回复、图片、轮播图等多种消息类型，并提供 React 组件和脚本标签两种集成方式。

环境准备

• 后端依赖：需要已运行且可访问的 Rasa (版本 2.3.x 或 2.4.x 推荐使用 webchat 1.0.1) 或 Botfront 服务器，并确保开启了 Socket.IO 接口。
• 前端环境：
  • 任意现代浏览器。
  • 若使用 React 集成方式，需具备 Node.js 和 npm 环境。
• 网络要求：确保前端页面能访问后端 socketUrl 地址。

安装步骤

根据您的需求选择以下任一集成方式：

方式一：通过 <script> 标签引入（无需构建工具）

直接在 HTML 文件的 <body> 标签内插入以下代码。此方式适用于静态网站或任何前端项目。

<script>!(function () {
  let e = document.createElement("script"),
    t = document.head || document.getElementsByTagName("head")[0];
  // 建议指定具体版本号以防止重大更新导致的不兼容，例如 @1.0.0
  (e.src = "https://cdn.jsdelivr.net/npm/rasa-webchat@1.x.x/lib/index.js"),
  (e.async = !0),
  (e.onload = () => {
    window.WebChat.default(
      {
        customData: { language: "en" },
        socketUrl: "https://bf-botfront.development.agents.botfront.cloud",
        // 在此处添加其他配置参数
      },
      null
    );
  }),
  t.insertBefore(e, t.firstChild);
})();
</script>

注意：请将 1.x.x 替换为您需要的具体版本（如 1.0.1），并将 socketUrl 替换为您自己的 Rasa/Botfront 服务器地址。

方式二：作为 React 组件安装

如果您使用的是 React 项目，可以通过 npm 安装：

npm install rasa-webchat

基本使用

1. 脚本标签模式示例

将以下代码保存为 index.html 并在浏览器打开即可看到聊天窗口（请替换 socketUrl 为您的实际地址）：

<!DOCTYPE html>
<html>
<head>
  <title>Rasa Webchat Demo</title>
</head>
<body>
  <h1>我的智能助手</h1>
  
  <script>!(function () {
    let e = document.createElement("script"),
      t = document.head || document.getElementsByTagName("head")[0];
    e.src = "https://cdn.jsdelivr.net/npm/rasa-webchat@1.0.1/lib/index.js";
    e.async = !0;
    e.onload = () => {
      window.WebChat.default(
        {
          customData: { language: "zh" }, 
          socketUrl: "http://localhost:5005", // 替换为您的 Rasa 服务器地址
          title: "AI 助手",
          inputTextFieldHint: "输入消息..."
        },
        null
      );
    },
    t.insertBefore(e, t.firstChild);
  })();
  </script>
</body>
</html>

2. React 组件模式示例

在您的 React 组件文件中引入并使用：

import Widget from 'rasa-webchat';

function CustomWidget = () => {
  return (
    <Widget
      initPayload={"/get_started"}
      socketUrl={"http://localhost:5500"}
      socketPath={"/socket.io/"}
      customData={{"language": "zh"}} 
      title={"欢迎使用助手"}
      // 如果希望嵌入页面而不显示启动按钮，设置 embedded={true}
      // embedded={true} 
    />
  )
}

核心配置参数说明

参数	说明
socketUrl	必填。Rasa 或 Botfront 服务器的 Socket 地址。
customData	传递给后端的自定义数据对象。若使用 Botfront，必须包含 {"language": "zh"} 等语言标识。
initPayload	会话开始时自动发送给 Rasa 的指令（如 /get_started）。
embedded	设为 true 可将聊天窗口直接嵌入页面，隐藏右下角的启动按钮，窗口默认常开。
title	聊天窗口标题栏显示的文本。