@ flow exact/ react-chatbot (英语)

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

选择集成方式

你需要一个 站点标识 从 流程引擎仪表板 (整合指南或站点设置).

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

先决条件

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

1. 安装

npm install @flowengage/react-chatbot

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

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

npm install @flowengage/react-chatbot@^1.0.0

2. 一次导入样式表

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

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

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

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

// 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 / 单列波

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

机板造型对编码( NamewidgetSettings(中文(简体) )

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

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

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

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

B1. 流动引擎CDN(建议)

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

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

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

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

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

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

Unpkg 上的等效路径 :

https://unpkg.com/@flowengage/[email protected]/dist/flowengage-embed.js

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

打开 <script> 标签 :

手动初始化

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

<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(中文(简体) )

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

可选:定制(npm)

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

<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>

<FlowEngageWidget>

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

使用 useFlowEngage 钩子

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

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

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

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

可用上下文值

SPA 路线跟踪

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

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. 登录到 流程引擎板
2. 打开 融合指南 或您的站点/ 工作空间设置
3. 复制 站点标识 用于您的网站

盖起嵌入层

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

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 属性存在于脚本标记上.

许可证

麻省理工学院