QQ WebChat - 嵌入式聊天

Webchat 2.0.0使用自来源访问者证书,需要匹配的NotChatbot后端和Cloudflare存在服务. 见 推出指南 在升级现有安装之前.

QQ 快速启动

1. 将部件添加到您的网站

<div id="webchat-component"></div>

<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
<script>
WebChat.initialize({
    title: "Customer Support",
    placeholder: "Ask us anything...",
    primaryColor: "#667eea"
});
</script>

2,就是这样

聊天机按钮将出现在您页面右下角 。 CSS自动注射!

QQ 配置选项

interface WebChatConfig {
  title?: string;                       // Chat window title
  placeholder?: string;                 // Input placeholder text
  primaryColor?: string;                // Primary theme color (also the user bubble)
  bubbleBotColor?: string;              // Bot bubble background ('' / omitted = #f1f2f4; text contrast adapts)
  apiKey?: string;                      // Your chatbot UID (required for API)
  position?: 'bottom-right' | 'bottom-left'; // Widget position
  initialMessage?: string;              // Custom initial bot message
  closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
  closeButtonText?: string;             // Text for close button (when type is 'text')
  closeButtonCustomIcon?: string;       // Custom icon SVG or URL (when type is 'custom')
  marginBottom?: number;                // Distance from bottom edge in pixels (default: 16)
  marginSide?: number;                  // Distance from left/right edge in pixels (default: 16)
  mobile?: WebChatPositionConfig;       // Mobile-specific position settings
  desktop?: WebChatPositionConfig;      // Desktop-specific position settings
  whatsapp?: {                          // Integrated WhatsApp Options
    phoneNumber: string;                // WhatsApp phone number
    message?: string;                   // Optional default message text
    active?: boolean;                   // Enable or disable the button (default: true)
    color?: string;                     // Customize the internal WhatsApp button color
  };
  apiBaseUrl?: string;                  // Backend override (see "Targeting a non-production backend")
  realtimeUrl?: string;                 // Convex deployment override (same section)
}

interface WebChatPositionConfig {
  position?: 'bottom-right' | 'bottom-left';
  marginBottom?: number;
  marginSide?: number;
}

示例

WebChat.initialize({
    title: "Chat Assistant",
    placeholder: "Type your message...",
    primaryColor: "#007bff",
    apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
    position: "bottom-right",
    initialMessage: "Hi! 👋 I'm your virtual assistant. How can I help you today?",
    closeButtonIcon: "default", // or "text" or "custom"
    marginBottom: 20,           // Distance from bottom edge (default: 16px)
    marginSide: 20,             // Distance from side edge (default: 16px)
    // Device-specific overrides
    mobile: {
        position: "bottom-left",
        marginBottom: 80,
        marginSide: 15
    },
    desktop: {
        position: "bottom-right", 
        marginBottom: 30,
        marginSide: 30
    },
    whatsapp: {                        // Adds a dual-button menu for WhatsApp & WebChat
        phoneNumber: "YOUR_PHONE_NUMBER",
        message: "Hello! I need help...",
        active: true,
        color: "#25D366"
    }
});

* 瞄准非生产后端

默认情况下, 部件会从它运行的页面主机名中选择其后端 关于: localhost → http://localhost:3000生产 (单位:千美元)https://next.notchatbot.com) (中文(简体) ). 这对商人来说是正确的 页面本身是非生产部署 vercel预览, dev.notchatbot.com,或者其它端口的本地 dev 服务器 超过三千. 没有覆盖,在预览中键入的消息会降落在 生产 收发箱.

apiBaseUrl 财务报告和审定财务报表 realtimeUrl 覆盖检测 :

WebChat.initialize({
    apiKey: "your-chatbot-uid",
    apiBaseUrl: window.location.origin,          // HTTP: /api/webchat, /upload, /rate
    realtimeUrl: "https://<deployment>.convex.cloud" // Convex realtime subscriptions
});

• 都一样 https:// (或 http://localhost 编号 : http://127.0.0.1任何东西 其它的则以控制台警告被忽略,默认值被保存.
• 把它们设为一对. apiBaseUrl 单写到一个部署时 部件继续监听默认的 Convex, 所以代理回复从未到达 .
• 让他们保持过去的行为—— 现有的嵌入物是 不受影响,每个 initialize() 清除先前呼叫中的任何更改.

QQWhatsApp 按钮

如果您想要一个没有 WebChat 的浮动WhatsApp 动作按钮, 您可以使用 WhatsAppButtonAPI,它将自己隔离在"阴影DOM"中来避免CSS冲突.

* 安装和基本使用

<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
  WhatsAppButtonAPI.initialize({
    phoneNumber: "1234567890",
    message: "Hola, me gustaría tener más información.",
    color: "#25D366",
    position: "bottom-right",
    marginBottom: 20,
    marginSide: 20,
    active: true,
    size: 48, // Button dimension in px
    
    // Customize device-specific positioning
    desktop: {
      position: "bottom-right",
      marginBottom: 30,
      marginSide: 30
    },
    mobile: {
      position: "bottom-right",
      marginBottom: 80,
      marginSide: 15
    }
  });
</script>

QQ 嵌入聊天 - 嵌入聊天

EmbedChat允许您将一个完整的聊天系统直接集成到您的网页的任何元素中,在大小,位置,和风格上完全控制.

* 安装和基本使用

直接 HTML

<!-- Element to embed the chat -->
<div id="my-chat-embed"></div>

<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
  EmbedChat.initialize({
    elementId: "my-chat-embed",
    apiKey: "your-api-key",
    title: "Chat Assistant",
    width: 400,
    height: 500
  });
</script>

Java 脚本/ Type 脚本

import { EmbedChatAPI } from './webchat';

const chatInstance = EmbedChatAPI.initialize({
  elementId: "my-chat-embed",
  apiKey: "your-api-key",
  title: "Chat Assistant",
  width: 400,
  height: 500
});

QQ 完整配置

必需属性

EmbedChatAPI.initialize({
  // REQUIRED
  elementId: "my-chat-embed",              // ID of the HTML element to embed the chat
  apiKey: "your-api-key",                  // API key of the service
})

内容属性

EmbedChatAPI.initialize({
  // Texts and content
  title: "Chat Assistant",        // Title shown in the header
  placeholder: "Type your message...",    // Input placeholder text
  initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
  footerText: "Powered by NotChatBot", // Footer text (optional)
  avatar: "https://example.com/avatar.jpg", // Bot avatar URL
})

大小属性

EmbedChatAPI.initialize({
  // Main dimensions
  width: 400,                        // Width: number (px) or string ("100%", "50vw")
  height: 500,                       // Height: number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,                     // Maximum width
  maxHeight: "90vh",                 // Maximum height (accepts CSS units)
  minWidth: 280,                     // Minimum width (default: 280px)
  minHeight: 300,                    // Minimum height (default: 300px)
})

外观属性

EmbedChatAPI.initialize({
  // Colors
  primaryColor: "#3b82f6",           // Primary color (header, buttons, etc.)
  textColor: "#333333",              // Message text color
  bubbleUserColor: "#3b82f6",        // User message bubble background
  bubbleBotColor: "#e0f2fe",         // Bot message bubble background (default #f1f2f4)
  chatBackground: "#ffffff",         // Chat background color
  footerColor: "#f3f4f6",            // Footer background color
  
  // Borders
  borderRadius: 12,                  // Border radius: number (px) or string
  border: "2px solid #3b82f6",       // Custom border (CSS border)
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  chatTransparent: false,            // If true, chat background is transparent
})

区域控制属性

EmbedChatAPI.initialize({
  showHeader: true,                  // Show/hide header (default: true)
  showFooter: true,                  // Show/hide footer (default: true if footerText is provided)
})

输入配置

EmbedChatAPI.initialize({
  input: {
    backgroundColor: "#ffffff",      // Input area background color
    inputBorder: "2px solid #e5e7eb", // Input field border
    inputBorderRadius: "8px",        // Input border radius
    iconColor: "#3b82f6"             // Send icon color
  }
})

自定义 CSS

EmbedChatAPI.initialize({
  customCSS: `
    #notchatbot-embed-chat {
      /* Your custom styles here */
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
    }
  `
})

大小控制

EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Main sizes
  width: 400,           // Number (px) or string ("100%", "50vw")
  height: 500,          // Number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,        // Maximum size
  maxHeight: "90vh",    // Can use CSS units
  minWidth: 280,        // Minimum size
  minHeight: 300,
  
  // More
  width: "100%",        // Occupies the entire width of the container
  height: "50vh",       // 50% of the window height
  maxWidth: "500px",    // Maximum 500px
})

视觉自定义

EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Borders and effects
  borderRadius: 12,                 // Border radius in px
  border: "2px solid #3b82f6",     // Custom border
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  // Section control
  showHeader: true,                 // Show/hide header (default: true)
  showFooter: true,                 // Show/hide footer (default: true if footerText is provided)
  
  // 🆕 Custom CSS
  customCSS: `
    #notchatbot-embed-chat {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
      border-radius: 20px !important;
    }
  `
})

完整属性参考

嵌入ChatConfig 配置表格

通过 API 和事件的动态控制

WebChat 让一个全局API和自定义事件从应用程序的任何地方或浏览器控制台动态控制部件的位置、粘贴和能见度 .

WebChat 全球方法

window.openWebChat();           // Open the floating chat
window.closeWebChat();          // Close the floating chat
window.toggleWebChat();         // Toggle open/close
window.unmountWebChat();        // Unmount the floating chat
window.mountWebChat();          // Mount the floating chat if it was unmounted
window.hideWebChat();           // Hide the chat (display: none)
window.showWebChat();           // Show the chat if it was hidden
window.injectWebChatCSS(css);   // Inject custom CSS into the shadow DOM
window.removeWebChatCSS();      // Remove custom CSS
window.setWebChatPosition(obj); // Change position/padding dynamically

嵌入式全球方法

window.unmountEmbedChat(elementId); // Unmount the EmbedChat instance for the given elementId
window.mountEmbedChat(elementId);   // Mount the EmbedChat instance again (with the last used config)

• window.unmountEmbedChat(elementId): 从指定的元素中卸载 EmbedChat 实例。 最后一个配置已保存 .
• window.mountEmbedChat(elementId): 使用该元素所用的最后一个配置在指定的元素中重载 EmbedChat 实例。 如果之前没有使用配置,则在控制台中显示警告.

示例

window.unmountEmbedChat('embed-small'); // Unmounts the chat from the element with id 'embed-small'
window.mountEmbedChat('embed-small');   // Remounts the chat in the same element with the last config

全球方法

您可以从 Global 窗口对象中编程显示、隐藏或销毁独立的WhatsApp 按钮.

window.WhatsAppButton.initialize(config); // Initializes the standalone widget
window.hideWhatsApp();                    // Hides WhatsApp button (display: none)
window.showWhatsApp();                    // Unhides it
window.unmountWhatsApp();                 // Removes from DOM entirely

倾听生命周期消息事件( X)

我们发射 自定义浏览器事件 所以,你可以捕捉到相互作用,把它们输入Google Tag管理器,Google分析器,Meta像素,或任何其他分析工具.

Message 遵循部件内部使用的相同接口(id、文本、发送者、时间戳等).

快速实例

window.addEventListener('notchatbot-webchat-open',  e => console.log('WebChat opened', e.detail));
window.addEventListener('notchatbot-webchat-closed',  e => console.log('WebChat closed', e.detail));
window.addEventListener('notchatbot-webchat-message-sent', e => console.log('Sent', e.detail.messages));
window.addEventListener('notchatbot-webchat-message-received', e => {
  const { role, message } = e.detail;
  console.log('Received', role, message);
});

Google 标签管理器 / Google 分析( GA4)

新来的: 上面列举的所有事件都会自动推向 数据 Layer 与此同时,与窗口事件同时发生! 这意味着你可以在 GTM 中创建触发器 notchatbot-webchat-message-sent 或者说 notchatbot-whatsapp-button-click 右出盒子, 不写手动JS事件听众.

如果您更喜欢自定义的数据结构,或者您需要清晰地映射信件内容,您仍然可以听 window 事件并手动推入数据Layer:

window.addEventListener('notchatbot-webchat-message-sent', e => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'webchat_message_sent',
    messages: e.detail.messages,
    conversationId: e.detail.messages[0]?.conversationId || null
  });
});

在GTM中,加一个 自定义事件 调用触发 webchat_message_sent (或 notchatbot-webchat-message-sent 并链接到 GA4 事件标记.

Meta / Facebook 像素

window.addEventListener('notchatbot-webchat-open', () => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatOpened');
  }
});

window.addEventListener('notchatbot-webchat-message-received', e => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatMessageReceived', {
      role: e.detail.role
    });
  }
});

这些事件使得在不修改源代码的情况下,很容易测量由聊天部件驱动的约定和转换.

动态改变位置并加载( WebChat)

1. 全球情况变化和比值(平面)

window.setWebChatPosition({
  position: 'bottom-left',
  marginBottom: 40,
  marginSide: 30
});

2. 仅用于移动的更改

window.setWebChatPosition({
  mobile: {
    position: 'bottom-right',
    marginBottom: 100,
    marginSide: 20
  }
});

3. 只更改桌面

window.setWebChatPosition({
  desktop: {
    position: 'bottom-left',
    marginBottom: 60,
    marginSide: 40
  }
});

4. 使用设备格式进行更改

window.setWebChatPosition({
  device: 'mobile',
  marginBottom: 120,
  marginSide: 15
});

使用自定义事件( addCustomPadding并打开/ 关闭控制)

您可以在应用程序的任意位置发送事件以更改粘贴/边距或打开/关闭聊天:

1. 打开、关闭或切换浮动的网络聊天

window.dispatchEvent(new CustomEvent('openWebChatbot'));
window.dispatchEvent(new CustomEvent('closeWebChatbot'));
window.dispatchEvent(new CustomEvent('toggleWebChatbot'));

2. 改变两个设备的垫(平面)

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));

3. 仅用于移动的更改

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));

4. 只更改桌面

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));

5. 使用嵌入对象更改

window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
  mobile: { marginBottom: 90, marginSide: 10 },
  desktop: { marginBottom: 50, marginSide: 30 }
}}));

接受对象格式

• 平地 : { marginBottom, marginSide, position } (如果移动/台式电脑没有覆盖,则适用于两者)
• 通过设备: { device: 'mobile'|'desktop', marginBottom, marginSide }
• 嵌入: { mobile: { ... }, desktop: { ... } }
• 别名: { y, x } (单位:千美元)y - 比特顿, x • 差值

您可以根据需要合并这些格式.

在 WebChat 中注入并删除自定义 CSS

您可以使用全球 API 在浮动 WebChat 中注入热CSS :

// Change the header background color
window.injectWebChatCSS(`
  #notchatbot-webchat-header {
    background: #111 !important;
    color: #fff !important;
  }
`);

// Hide the floating button
window.injectWebChatCSS(`#notchatbot-webchat-button { display: none !important; }`);

// Change the chat window width
window.injectWebChatCSS(`#notchatbot-webchat-window { width: 500px !important; }`);

// Change the floating button color
window.injectWebChatCSS(`#notchatbot-webchat-button { background: #f59e0b !important; }`);

// Remove all custom styles
window.removeWebChatCSS();

WebChat 的内部元素ID

您可以使用这些ID来选择和样式部件的特定部分 :

• #notchatbot-webchat-button — 浮动聊天按钮
• #notchatbot-webchat-header —聊天窗口头
• #notchatbot-webchat-window —主聊天窗口

修改标题和按钮颜色的示例 :

window.injectWebChatCSS(`
  #notchatbot-webchat-header { background: #222 !important; color: #fff !important; }
  #notchatbot-webchat-button { background: #f59e0b !important; }
`);

您可以把这些选择器组合起来, 完全定制部件 .

信息泡的稳定类

信息泡(WebChat and EmbedChat) 搭载稳定类,安全可瞄准来自 injectWebChatCSS 或者说 customCSS数字 :

• .nbc-bot-bubble ——瓶/剂信息泡
• .nbc-user-bubble - 访客信息泡泡
• .nbc-bubble-tail - 每个气泡上角的小尾巴

泡泡背景画有 var(--nbc-bubble-bg, <configured color>),尾部和可选菜单会逐渐消失。 文本(信息、时间、回复引文和菜单图标)用 var(--nbc-bubble-fg, <computed text color>)设置自定义属性,而不是 background 编号 : color 所以一切都会一起改变,没有 !important数字 :

window.injectWebChatCSS(`
  .nbc-bot-bubble { --nbc-bubble-bg: #e0f2fe; }
  .nbc-user-bubble { --nbc-bubble-bg: #1e293b; --nbc-bubble-fg: #ffffff; }
`);

默认文本颜色是从所配置的颜色计算出来的( )bubbleBotColor / 主色调),不是来自 CSS 覆盖. 当覆盖变化很大时, 也会设置 --nbc-bubble-fg 在同一类(平地) color 或更喜欢 bubbleBotColor 选项,可自动选择可读文本.