# @flowengage/react-chatbot 中文文档

规范地址：https://npmcn.com/package/%40flowengage/react-chatbot/

版本：8\.0\.173
npm 元数据更新时间：2026-11-10T13:10:25.885Z
中文译文更新时间：2026-11-15T00:16:37.033Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flowengage/react-chatbot
原文对照：https://npmcn.com/package/%40flowengage/react-chatbot/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-04-07T16:57:31.245Z
- 最新版本发布：2026-11-10T13:10:25.164Z
- 近 30 天下载量：4571（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：485（近 12 个月 485 个）

## 中文简介

嵌入式 AI 聊天部件 React ——由 FlowEngage 提供动力. 用一个网站的地址把它放进去.

## 安装

```sh
npm install @flowengage/react-chatbot
```

也可以使用：`pnpm add @flowengage/react-chatbot`、`yarn add @flowengage/react-chatbot`、`bun add @flowengage/react-chatbot`

## README

# @ flow exact/ react-chatbot (英语)

可嵌入的 AI 驱动客户支持聊天部件——由 [流动引擎](https://flowengage.com/)。 。 。 .  
增加现场聊天,AI助手, 和代理交接到任何网站在几分钟内。 你需要的就是你们的 **站点标识**。 。 。 .

* * *

## 选择集成方式

| 方针 | 最好还是 | 你加的这个 |
| --- | --- | --- |
| **npm 软件包** | React, Next.js, Vite, Remix 等 (英语). | 安装软件包, 用软件包 `FlowEngageProvider`时 `FlowEngageWidget`。 。 。 . |
| **CDN (标记标记)** | Plain HTML, PHP, 任何CMS, 非反应的 SPA | 一个 `<script>` 标签; 样式被捆绑入嵌入- 没有单独的 CSS 文件 . |

你需要一个 **站点标识** 从 [流程引擎仪表板](https://app.flowengage.com/) (整合指南或站点设置).

* * *

## A. npm 软件包( React / Next.js / Vite)

### 先决条件

-   **反应 18+** 财务报告和审定财务报表 **反应分数 18+** 在您的项目中( 类依赖性) .
-   18+节点推荐地方发展.

### 1\. 安装

```bash
npm install @flowengage/react-chatbot
```

```bash
# or
yarn add @flowengage/react-chatbot
pnpm add @flowengage/react-chatbot
```

如果您喜欢可复制的构建, 请在生产中插入一个版本 :

```bash
npm install @flowengage/react-chatbot@^1.0.0
```

### 2\. 一次导入样式表

部件自带CSS 在您的应用程序条目( 或版式文件) 导入它 :

```js
import '@flowengage/react-chatbot/styles.css';
```

### 3\. 包装您的应用程序并挂载部件

`FlowEngageProvider` 必须覆盖使用的任何组件 `FlowEngageWidget` 或者说 `useFlowEngage`。 。 。 .

```jsx
// e.g. App.jsx, main.jsx, or a root layout wrapper
import { FlowEngageProvider, FlowEngageWidget } from '@flowengage/react-chatbot';
import '@flowengage/react-chatbot/styles.css';

export default function App() {
  return (
    <FlowEngageProvider siteId="YOUR_SITE_ID">
      <YourExistingApp />
      <FlowEngageWidget />
    </FlowEngageProvider>
  );
}
```

### Next.js App路由器

-   把提供者+部件放入一个 **客户部分** (档案有: `"use client"` ),或客户端包装从 `layout.tsx`。 。 。 .
-   保留单一的提供者树, 以便共享聊天状态 .

### Yarn / 单列波

确保软件包在应用级别解决一次, 这样您就不会挂载重复的提供者 .

### 机板造型对编码( Name`widgetSettings`(中文(简体) )

使用 **仅限** `siteId` (和可选) `apiBaseUrl` 用于本地 dev ) `FlowEngageProvider` 所以部件 **装入品牌、主题、问候和流程引擎仪表板的建议** 与CDN嵌入的一样.

如果你也通过 `config={{ widgetSettings: { ... } }}`,这些字段将起到 **仅默认**· ; **已保存的仪表板设置覆盖** 他们。 避免在您的应用程序中粘贴完整的部件 JSON, 除非您有意想要离线默认; 否则您必须在每次仪表盘更改后更新代码 .

* * *

## B. CDN / 脚本标记( 不需要反应项目)

嵌入式建筑包括回放和自动注入样式. 没错 **没有** 导入 `styles.css` 当使用脚本时.

### B1. 流动引擎CDN(建议)

使用主机脚本( 与 FlowEngage 基础设施同步) :

```html
<script
  src="https://cdn.flowengage.com/flowengage-embed.js"
  data-site-id="YOUR_SITE_ID"
  defer>
</script>
```

打开这个 **在此之前 `</body>`** ,或者在您的全局主题模板中.

### B2. npm 注册 CDN (pin a 版本)

如果您喜欢加载已出版的同一件文物到 npm( 用于打针或离线镜像):

```html
<!-- Replace 1.0.0 with the version you want -->
<script
  src="https://cdn.jsdelivr.net/npm/@flowengage/react-chatbot@1.0.0/dist/flowengage-embed.js"
  data-site-id="YOUR_SITE_ID"
  defer>
</script>
```

Unpkg 上的等效路径 :

`https://unpkg.com/@flowengage/react-chatbot@1.0.0/dist/flowengage-embed.js`

### 自动动属性( E)`data-*`(中文(简体) )

打开 `<script>` 标签 :

| 属性 | 需求 | 说明 |
| --- | --- | --- |
| `data-site-id` | 自动动画 | 仪表盘上的站点标识. |
| `data-api-url` | ❌ | 覆盖 API 基础 URL( 高级; 通常省略) . |
| `data-widget-settings` | ❌ | 运行时部件的JSON字符串会覆盖(主题,品牌). 示例 `'{"theme":{"primaryColor":"#2563EB"}}'` |

### 手动初始化

如果无法使用 `data-site-id` 在脚本标签上 :

```html
<script src="https://cdn.flowengage.com/flowengage-embed.js" defer></script>
<script>
  window.addEventListener('load', function () {
    window.FlowEngage.init({
      siteId: 'YOUR_SITE_ID',
      widgetSettings: {
        theme: { primaryColor: '#2563EB', position: 'bottom-right' },
        branding: { headerName: 'Support', chatButtonText: 'Chat' },
      },
    });
  });
</script>
```

### CDN API (英语:`window.FlowEngage`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `FlowEngage.init({ siteId, widgetSettings?, apiBaseUrl? })` | 挂载部件。 之后可以安全打电话 `DOMContentLoaded`。 。 。 . |
| `FlowEngage.destroy()` | 卸载部件并删除所注入的样式/容器。 打电话之前 `init` 如果您需要重新配置, 请再次配置 . |

从自定义的 UI 打开/关闭面板 **反应** 应用程序,使用 npm 软件包和 `useFlowEngage()` (单位:千美元)`openWidget`, (中文(简体) ), `closeWidget`(见A/C.5/49/70,附件)。 独立嵌入体暴露 `init` 编号 : `destroy` 只有这个.

* * *

## 可选:定制(npm)

通过运行时间覆盖 `config` 在提供者上(与仪表板默认合并):

```jsx
<FlowEngageProvider
  siteId="YOUR_SITE_ID"
  config={{
    widgetSettings: {
      theme: {
        primaryColor: '#FF5733',
        position: 'bottom-left',
      },
      branding: {
        headerName: 'Cool Support Assistant',
        chatButtonText: 'Talk to us',
      },
    },
  }}
>
  <FlowEngageWidget />
</FlowEngageProvider>
```

* * *

## 道具

### `<FlowEngageProvider>`

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `siteId` | `string` | ✅ | FlowEngage 仪表板上的站点标识 |
| `config` | `object` | ❌ | `{ widgetSettings?: … }` 与服务器配置合并 |

### `<FlowEngageWidget>`

无需道具. 从最近的状态读取 `FlowEngageProvider`。 。 。 .

* * *

## 使用 `useFlowEngage` 钩子

访问任何子组件的完整部件上下文 :

```jsx
import { useFlowEngage } from '@flowengage/react-chatbot';

function MyCustomButton() {
  const { openWidget, isOpen, chatHistory } = useFlowEngage();

  return (
    <button type="button" onClick={() => openWidget()}>
      Chat ({chatHistory.length} messages)
    </button>
  );
}
```

### 可用上下文值

| 数值 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `"booting" | "ready" | "error"` | 部件启动状态 |
| `isOpen` | `boolean` | 聊天面板是否打开 |
| `chatHistory` | `Message[]` | 完整聊天历史阵列 |
| `isHumanHandled` | `boolean` | 现场特工是否接手 |
| `agentName` | `string | null` | 活动代理名称 |
| `agentHeadshot` | `string | null` | 活动代理的外观 URL |
| `isAgentTyping` | `boolean` | 代理打字指标 |
| `isLoading` | `boolean` | 等待大赦国际的答复 |
| `isVoiceMode` | `boolean` | 语音模式活动 |
| `isRateLimited` | `boolean` | 费率限制 |
| `openWidget()` | `function` | 打开聊天面板 |
| `closeWidget()` | `function` | 关闭聊天面板 |
| `toggleWidget()` | `function` | 切换面板 |
| `sendMessage(msg, category?)` | `function` | 发送消息 |
| `setVoiceMode(bool)` | `function` | 切换语音模式 |
| `notifyRouteChange()` | `function` | 通知 SPA 路由变化的跟踪器 |

* * *

## SPA 路线跟踪

对于客户端路由(React Router, Next.js App Router等):

```jsx
import { useFlowEngage } from '@flowengage/react-chatbot';
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function RouteTracker() {
  const { notifyRouteChange } = useFlowEngage();
  const location = useLocation();

  useEffect(() => {
    notifyRouteChange();
  }, [location.pathname]);

  return null;
}
```

* * *

## 语音模式

部件包括一个11Labs驱动的语音代理,访问者可以与无手互动.

### 届会周期

1.  访问者点击"Start Voice"(或自动启动于语音辅助网站)
2.  部件从后端获取一个签名的 URL( W)`GET /api/voice/signed-url`(中文(简体) )
3.  十一Labs WebSocket 会话以页面格式问候覆盖开始
4.  代理可以调用客户端工具 : `flowengage_navigate`, (中文(简体) ), `flowengage_highlight`, (中文(简体) ), `flowengage_list_forms`, (中文(简体) ), `flowengage_fill_form`, (中文(简体) ), `flowengage_click_button`, (中文(简体) ), `end_voice_session`
5.  在 SPA 导航上, 会话持续存在 — 一个 URL 更改跟踪器发送背景更新, 以便代理商知道当前页面
6.  在硬通航(页重装)时,记录稿被保存到 `sessionStorage` 和会话自动复会

### 跨页面重载语音恢复

当代理浏览到新页面时(`flowengage_navigate`,部件 :

-   保存当前记录和复写旗 `sessionStorage`
-   触发硬重装或 SPA 路由更改
-   在新的一页, `useLayoutEffect` 检测待定的恢复和重新进入 `voice_mode`
-   新的会话带有"继续巡演"的序言,所以代理员会捡起它留下的地方

### 所需资源

-   11Labs探员必须 `first_message` 在平台设置中启用了覆盖
-   后端必须 `ELEVENLABS_API_KEY` 配置
-   访客必须获得麦克风许可

* * *

## 如何运作

```
Your App
   └── <FlowEngageProvider siteId="...">
          │
          ├── Boot:  GET /api/widget/bootstrap  → validates siteId, returns config
          ├── Start: POST /api/ai/chat           → loads chat history
          ├── Chat:  Socket.IO                   → real-time messages & agent handoff
          ├── Voice: GET /api/voice/signed-url   → ElevenLabs WebSocket voice session
          └── Track: Socket.IO events            → visitor session, page views
```

后端 URL 由 FlowEngage 解决;通常不设置,除非使用 `apiBaseUrl` (先入为出.

* * *

## 获取您的站点ID

1.  登录到 [流程引擎板](https://app.flowengage.com/)
2.  打开 **融合指南** 或您的站点/ 工作空间设置
3.  复制 **站点标识** 用于您的网站

* * *

## 盖起嵌入层

CDN嵌入是包含React,所有部件代码和内置CSS的IIFE捆绑. 以 :

```bash
FLOWENGAGE_API_URL=https://your-api-url npx vite build --config vite.embed.config.js
```

产出土地 `dist/flowengage-embed.js`。将此文件复制到 CDN 或后端 `public/` 服务文件夹.

这个 `FLOWENGAGE_API_URL` env var 在构建时被烤入捆绑中 — 部件将其作为默认的 API 基础 URL 当没有时 `data-api-url` 属性存在于脚本标记上.

* * *

## 许可证

麻省理工学院

## 常见问题

### @flowengage/react-chatbot 是什么？

嵌入式 AI 聊天部件 React ——由 FlowEngage 提供动力\. 用一个网站的地址把它放进去\.

### 如何安装 @flowengage/react-chatbot？

在项目目录运行 npm install @flowengage/react-chatbot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flowengage/react-chatbot 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flowengage\_\_react-chatbot 是否存在。

### @flowengage/react-chatbot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flowengage/react-chatbot 可以商用吗？

@flowengage/react-chatbot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flowengage/react-chatbot 的下载量有多少？

根据 npm 官方下载统计，@flowengage/react-chatbot 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,571 次，日均约 152 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flowengage/react-chatbot 还在维护吗？

最新版本 8\.0\.173 发布于 2026/11/10（5 天前）；至今共发布 485 个版本，其中过去 12 个月发布了 485 个；首次发布于 2026/04/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。