聊天小部件 #

网站聊天小部件集成指南 #

在您的网站上添加一个用户友好的聊天小部件，使访客能够直接通过您网站的界面进行沟通。集成过程非常简单，并将为您的网站提供内置的消息传递功能。

创建和配置聊天小部件 #

如何操作：

1. 点击左侧边栏底部的 Settings（设置）。（在手机上，请先点击角落的菜单图标 ☰ 以打开侧边栏。）
2. 在“设置”左侧导航栏中，点击 Channels（渠道）下的 Channels（渠道）。
3. 找到 Website chat widget（网站聊天小部件）卡片。
4. 如果您还没有小部件，请点击 Connect（连接）以创建一个带有显示名称和欢迎消息的小部件。
5. 创建完成后，您可以随时点击 Manage（管理）打开完整的配置面板。

您保存的更改会自动应用到您的实时小部件中 — 进行更改后无需重新粘贴安装代码。

设置旁边即是实时预览：一个展示您实际小组件的网页示例，它会显示您的颜色、位置、徽标、启动图标和主动弹窗，效果与访客看到的一模一样。它会跟随您的编辑实时更新，因此您无需保存即可查看颜色或主题更改后的效果。您甚至可以点击预览中的聊天按钮来打开小组件并进行试用。

您可以自定义的内容 #

“管理”面板分为四个部分。

外观 #

• 样式主题： 一键重塑整个小部件的风格。六种主题分别统一设置外观、颜色、圆角和字体：经典 (Classic)（原始的纯色外观——扁平面板上的彩色标题栏）、玻璃 (Glass)（一种磨砂半透明面板，可柔和地模糊其后的页面，标题和消息框作为圆角卡片浮动在其中）、午夜 (Midnight)（深色调的玻璃主题）、绽放 (Bloom)（柔和的粉色，更圆润）、余烬 (Ember)（暖橙色玻璃主题）和 单色 (Mono)（黑白配色，直角边缘）。主题只是一个起点——选择主题后，您仍然可以单独更改任何颜色或设置。
• 圆角和字体： 两个独立的样式调节选项。圆角 (Corners) 设置面板、气泡和按钮的圆润程度（圆角、柔和或直角），字体 (Font) 选择访客看到的字体（默认、衬线体、圆体或等宽体）——字体直接调用访客设备上已有的字体，因此不会在您的网站上加载额外资源。
• 显示名称： 显示在小部件标题中。
• Logo： 上传一张显示在聊天窗口顶部图片。可以使用公司 Logo 或亲切的头像。
• 启动图标： 浮动聊天按钮上的图标。您可以选择内置图标（聊天气泡、纸飞机、问号等）、重复使用已上传的 Logo，或上传一张单独的图片——如果您希望使用真实团队成员的照片来问候访客，这非常方便。
• 颜色： 五种颜色，每种颜色对应小部件的特定部分。品牌颜色 (Brand color) 用于浮动按钮、标题和访客自己的消息，品牌文字 (Brand text) 用于其上的文字。机器人气泡 (Bot bubble) 是机器人回复和输入指示器的背景，机器人气泡文字 (Bot bubble text) 用于其中的文字和动态输入点。聊天窗口 (Chat window) 是所有消息背后的面板。请选择一种与您的品牌颜色明显不同的机器人气泡颜色——如果两者颜色相同，对话双方的颜色就会一样，访客将无法区分机器人和自己的回复。浅灰色机器人气泡搭配深色文字与您的品牌颜色组合通常是稳妥的选择。
• 位置： 将浮动聊天按钮放置在页面的右下角或左下角，如果它遮挡了页面上的其他内容，还可以设置水平和垂直偏移量（以像素为单位）。
• 引导问题： 聊天中显示的快速回复建议（可点击的卡片），让访客只需轻点一下即可开始对话，无需打字——例如“你们的价格是多少？”或“你们提供支持吗？”——最多可设置 10 个。
• 页脚行： 消息框下方可选的一行小字，例如“由您的代理机构提供支持”。默认情况下它是关闭的，关闭时消息框下方不会显示任何内容。开启后，输入您的文本（最多 40 个字符），如果需要，还可以添加以 https:// 开头的链接；访客点击该文本时会在新标签页中打开该页面。代理机构通常用它来在为客户构建的小部件上标注自己的名称。

行为 #

• 开场消息： 访客打开聊天窗口时看到的第一条消息（例如：“有什么我可以帮您的吗？”）。
• 声音： 当聊天中收到新消息时播放提示音。
• 请求通知权限： 可选地提示访客允许浏览器通知，这样即使他们切换了标签页，也能收到回复提醒。
• 主动弹窗气泡： 一个可选的小气泡，会在聊天按钮旁边弹出以邀请访客。开启后可设置其消息内容、接受/拒绝按钮的文本，以及显示前的等待秒数。如果访客未点击，气泡会在 20 秒后自动关闭。这是小部件在聊天按钮旁边显示的唯一文本：没有设置可用于在按钮旁边显示永久标签。
• AI 响应速度： 一个在 较慢（更像人类——AI 回复前会稍作停顿）和 最快（更像机器人——回复尽可能快地返回）之间的滑块。平衡模式位于中间。回复的第一条消息会在滑块设置的延迟后到达，输入指示器会在此前不久显示。
• AI 工作时显示忙碌提示： 默认关闭。当回复需要几秒钟以上的时间时（例如因为您的智能体正在其他系统中查找信息），访客会在输入点旁边看到一行简短的文字：5 秒后显示“正在为您准备答案”，15 秒后显示“正在为您查找”，如果时间更长，则会显示“仍在处理中，马上就好”并附带等待歉意。快速回复仍仅显示输入点。该行文字遵循小部件的语言设置，且仅在 AI 实际处理回复时出现，当该聊天中 AI 已关闭或人工已接管时不会显示。

语言 #

该小部件本身支持多语言，无需进行任何设置。

• 它会自动选择访客的语言。 首先，它会查看您的页面在 HTML 中声明的语言 (<html lang="it">)，然后会回退到访客的浏览器语言。如果这两种都不是我们支持的语言，小部件自身的标签将以您编写开场白时所用的语言显示，而您的开场白、弹出气泡和引导问题将完全按照您编写的内容显示。

• 与您的问候语相矛盾的页面语言不会被采信。 一些网站构建器会在每个页面上放置 lang="en"，无论网站实际使用什么语言。当页面声明一种语言而您用另一种语言编写开场白时，小部件会将页面值视为构建器的默认设置：它会转而遵循访客的浏览器语言；如果该语言也不是我们支持的语言，它将使用您编写时所用的语言。如果页面在访客选择语言时会切换其 lang 值，则始终遵循该值。如果您不想依赖这些机制，可以在“行为”部分固定语言。

• 或者您可以自行选择。 “行为”部分中的小部件语言字段默认设置为“自动”，即上述的检测机制。在此处选择一种语言，无论页面或浏览器如何设置，小部件自身的标签（访客表单的“名字”、“电子邮件”和“电话”字段及其示例文字、隐私声明、按钮）都将保持为该语言。当您的网站构建器无法声明正确的语言，或者您希望所有访客都使用固定的语言时，请使用此功能。

• 支持的语言： 英语、荷兰语、德语、法语、西班牙语、意大利语、葡萄牙语、罗马尼亚语、波兰语、阿拉伯语、芬兰语、菲律宾语、斯洛文尼亚语、泰语、孟加拉语、日语、挪威语（书面挪威语）和土耳其语。这是小部件自身按钮和标签所支持的语言列表。

• 从右到左的语言采用从右到左的布局。 对于阿拉伯语、希伯来语、波斯语和乌尔都语的访客，整个聊天窗口会进行镜像处理：标题、消息气泡、输入提示点、访客表单和消息框全部从右侧开始。气泡按钮保持在您选择的角落。希伯来语、波斯语和乌尔都语的访客看到的标签是英语（或您固定的语言），但布局仍遵循其语言习惯。以不同方向书写的消息（例如阿拉伯语聊天中的英语回复）仍会按正确的顺序阅读。

• 您的消息会自动为您翻译。 每次保存时，您的开场白、主动弹出气泡和引导问题都会被翻译成上述所有十八种语言。您只需用您喜欢的任何语言编写一次：系统会从文本本身识别出您编写的语言，该版本将逐字保留，而其他所有语言都是其翻译版本。您的账户设置为哪种语言并不重要。

• 为特定语言编写您自己的版本。 “管理”面板中“行为”下方的翻译部分，允许您用自己的措辞替换自动翻译，例如在自动翻译为非正式用语时，使用正式的西班牙语（“usted”）。在语言下选择一种语言，然后填写以下任意字段：开场白、弹出消息、弹出窗口的接受文本和拒绝文本（在弹出气泡显示时可见）以及引导问题。每个字段都会以灰色显示自动翻译；从自动翻译开始按钮会将其复制过来，以便您在此基础上进行编辑。您留空的任何内容都将保留自动翻译。您自己编写的语言会列在最前面，并标记为您自己的措辞，点击移除我的（语言）措辞即可恢复为该语言的自动翻译。当您稍后编辑原始文本时，您自己的措辞会被保留；只有自动翻译会被重新生成。

• 弹出按钮也会被翻译。 主动弹出气泡的“接受”和“拒绝”按钮会与您的其他消息一起翻译，因此西班牙语访客不再会看到英语按钮。

• 每条消息仅用一种语言编写。 如果您在同一个字段中放入两种语言（例如一行英语和一行意大利语），整段内容会被视为一条消息并按原样翻译，导致意大利语访客最终看到两次相同的句子。请用您喜欢的语言编写一次即可。

• AI 会以访客的语言进行回复。 无论对方输入什么语言，您的代理都会以相同的语言回答，而不受小部件标签显示语言的影响。如果您希望它始终以固定的语言回答，请在代理的指令中说明。

• 在嵌入代码中按页面设置语言。 在英语网站上运行一个小部件，并使用其翻译副本？请在每个页面的小部件脚本标签中添加 data-lang。data-lang="es" 会使小部件在该页面上以西班牙语显示，无论浏览器如何设置；data-lang="page" 会使其遵循页面自身的 <html lang="..."> 值（因此 lang="es-MX" 会显示为西班牙语），即使您的开场白是用另一种语言编写的。它的优先级高于小部件语言字段，而该字段的优先级又高于自动检测。例如：

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" data-lang="page" defer></script>

保持“管理”面板中的嵌入代码不变，仅添加 data-lang 属性。对于内嵌聊天面板，请将 data-lang 放在 <div data-chat-widget="…"> 上。

提示： 如果您的网站未在 <html> 标签上设置 lang 属性，请添加一个。这是我们选择正确语言的最强信号，特别是对于在国外浏览的访客而言。

线索捕获与隐私 #

• 收集访客信息： 默认关闭。开启后，访客在对话开始前会被要求提供姓名和电子邮件（可选电话），以便您即使在他们中途离开时也能获取潜在客户信息。
• 表单标题和表单副标题： 自定义表单上方显示的标题和简短说明。
• 收集电话号码： 开启后会同时询问电话号码；关闭则仅收集姓名和电子邮件。
• 收集姓氏： 默认关闭。开启后会在“名字”字段后添加一个必填的姓氏字段。它将作为联系人的姓氏保存，因此您的 AI 以及它在您系统中查找的任何内容都能从第一条消息中获取完整姓名。在您开启此功能前已填写过表单的访客不会被再次询问。
• 向访客发送未读回复邮件： 如果访客留下了电子邮件地址，且在 15 分钟后仍未查看您的回复，系统会向其发送一封邮件引导他们回到聊天窗口。可在“设置”→“通知”→“聊天小部件访客”下关闭此功能。请参阅 向聊天小部件访客发送邮件。

访客留下了电话号码并离开了您的网站——我可以在 WhatsApp 上继续对话吗？ 可以。打开他们的聊天记录，从三点菜单中选择 在 WhatsApp 上继续（需要连接 WhatsApp Web 或 WhatsApp Business）。Your AI Connector 会为同一个人创建一个关联的 WhatsApp 对话，复制他们的姓名、电子邮件和详细信息，AI 也会延续他们在您网站上所说的话，因此无需重复沟通。网站聊天记录会保留在原处，且两个聊天记录都会在联系人面板的 关联对话 下相互指向。请参阅 聊天界面。

访客留下了邮箱但未预订——我可以通过电子邮件跟进吗？ 可以，使用自动化功能即可。一个将 Channel（渠道）设置为 Email（电子邮件）的 Create contact（创建联系人）步骤，会将访客留下的地址转换为您已连接的 Email channel（电子邮件渠道）上的电子邮件联系人，随后的 Send message（发送消息）步骤则会以电子邮件形式发出；回复将进入 Chats（聊天）中，供您的电子邮件代理处理。完整的方案，包括如何在他们表示已预订后停止序列，请参阅 Automations → Example: email follow-ups for website chat leads（自动化 → 示例：针对网站聊天潜在客户的电子邮件跟进）。

AI 代理可以主动提议切换到 WhatsApp 吗？ 可以，而且不需要额外功能——只需在代理的指令中加入一行即可。为您的 WhatsApp 号码创建一个 短链接，并附带预填信息，例如“您好，我刚才在您的网站上聊天，想在这里继续”，然后告诉代理何时发送该链接，例如：“如果访客需要离开、想稍后继续或询问 WhatsApp，请提议在那里继续并发送此链接：（您的短链接）”。小组件中的链接可点击，因此访客会进入 WhatsApp，选中您的号码并预填好消息，他们的第一条消息就会在您的收件箱中开启一个 WhatsApp 对话。如果访客在小组件表单中留下了他们发送消息时使用的电话号码（含国家代码），Your AI Connector 会自动关联这两个对话，WhatsApp 上的 AI 也会像 在 WhatsApp 上继续 功能一样，直接获知网站上的聊天内容。如果没有收集到电话号码，这两个聊天记录将不会关联，因此请确保预填信息足够具体，以便 WhatsApp 代理知道此人来自何处。

• 要求确认隐私政策： 可选要求访客在聊天前接受您的隐私政策，并设置其指向的 URL。

该小部件在访客的浏览器中存储了什么？我需要将其放在 Cookie 横幅之后吗？ 仅加载页面时不会存储任何内容。在访客选择聊天（发送第一条消息、填写访客信息表单或接受您的隐私政策）之前，该小部件不会写入任何 Cookie 或浏览器存储。从那一刻起，它会将随机的对话 ID 和对话副本保存在该浏览器中，作为您自己域名下的第一方存储，以便访客回来时聊天记录依然存在。它不会加载任何分析或跟踪脚本，也不会设置任何第三方 Cookie。由于在访客主动发起聊天之前不会写入任何内容，因此它属于访客所请求服务严格必需的存储，您可以直接加载它，无需将其放在同意横幅之后。如果您的网站无论如何都在使用同意工具，将其放在该工具之后也是可以的；访客接受后，聊天窗口就会显示出来。

渠道与嵌入 #

• 附件按钮： 允许访客在聊天中发送图片和文件。
• 表情符号选择器： 在消息框旁边添加一个表情符号选择器。
• 渠道链接： 可选地包含 WhatsApp、Instagram 或 Messenger 链接，以便访客可以在他们偏好的平台上继续对话。此选项仅在您连接了 WhatsApp 号码（WhatsApp Business 或 WhatsApp Web）、Instagram 或 Messenger 后才会显示。开启 WhatsApp 链接会自动填入您已连接的号码；该链接仍可编辑，因此在更换号码后，您可以手动输入新的号码。
• 操作按钮： 聊天窗口顶部的一排快捷方式，点击后会将访客引导至其他页面而非进入对话——请参阅下方的 操作按钮。
• 域名白名单： 限制允许嵌入您小部件的网站。添加您已安装该小部件的域名（例如 example.com 或 *.example.com）；留空则允许任何域名。
• 屏蔽国家/地区： 防止您未提供服务的国家/地区的访客看到小部件。网络位置在您所选国家/地区的访客将永远看不到该小部件，且他们尝试发起的任何聊天都将被拒绝。留空则允许所有人访问。请参阅下方的 防止机器人和信用消耗。
• 将这些聊天路由至： 选择应处理来自您即将复制的代码的聊天的坐席。保持在 账户默认 即可使用您常规的聊天小部件路由。请参阅下方的 将不同页面发送给不同坐席。
• 嵌入代码片段： 选择 悬浮气泡 或 内嵌 并复制安装代码（见下文）。
• 客户演示链接： 粘贴任何网站地址并点击 创建链接，即可获得一个可共享的链接。该链接打开后会显示加载了您小部件的网站，对方无需安装任何内容。您创建的每个链接都会被列出，您可以随时关闭其中的任何一个。请参阅下方的 在他人网站上显示小部件。
• 分享链接： 一个现成的链接，可在独立页面上全屏打开您的助手，无需网站支持。复制并发送到任何地方即可。请参阅下方的 分享聊天直接链接。

在面板底部，删除聊天组件操作会立即从您的网站上移除该组件——此操作无法撤销，访客将不再看到聊天气泡。

操作按钮 #

有些访客不想聊天。他们想要您的电话号码、地址或电子邮件，并且希望一键获取。操作按钮就是聊天面板顶部的一排快捷方式，专门用于实现此目的。

最多可添加六个。每个按钮都有一个 标签（按钮上的文字）和一个 目标地址，目标地址取决于您选择的操作：

这些按钮不消耗额度。 点击按钮不会发送消息，也不会开始对话——它只是将访客带到他们要求去的地方。只有与您的 AI 坐席进行的实际对话才会消耗额度，与之前完全一样。

几点值得注意的事项：

• 按钮在访客聊天时保持可见。 访客可以提出两个问题，之后无需重新加载页面即可点击 路线指引。
• 您的标签将按您书写的原样显示。 与您的开场白和引导问题不同，按钮标签不会自动翻译。因此，如果您为多种语言的访客提供服务，请保持标签简短且直观（或使用您的主要语言书写）。
• 必须正确填写按钮信息，否则无法保存。 如果电话号码、电子邮件地址或链接无效，面板会提示并阻止 保存更改，而不是发布一个在您的网站上无法使用的按钮。
• 它们不是常见问题解答。 操作按钮只会将访客引导至其他地方；它们不会回复预设文本。回答问题是您 AI 坐席的工作，它会根据您的知识库进行回答。如果您想建议访客询问什么，请使用“外观”下的 引导问题。

无法自定义的内容 #

“管理”(Manage) 面板包含了所有的选项。具体来说：

• 无自定义 CSS 或样式表。 样式仅限于主题、圆角、字体和颜色选择器所提供的选项——你无法将自己的 CSS 注入到小部件中，页面上的规则也无法作用于其内部。
• 消息框中无自定义占位符文本。
• 聊天中无视频嵌入功能。

如果其中任何一点对你造成了阻碍，内联嵌入可以为你提供最大的控制权：小部件位于你页面上的一个容器中，其大小和位置均由你自行决定。

防止机器人和信用消耗 #

每次 AI 回复都会消耗信用额度，因此脚本（或某个无聊的人）在您的网站上不断开启聊天是公共小部件必须防范的问题。小部件本身可以处理大部分此类情况，而“管理”面板上的两个设置可让您针对您的网站加强防护。

• 域名白名单。 只有您列出的网站才能显示该小部件。任何将您的嵌入代码复制到其他网站的人都无法看到任何内容。
• 屏蔽国家/地区。 网络位置在您屏蔽的国家/地区内的访客将永远看不到该小部件，即使他们尝试发起聊天也会被拒绝。位置信息来自访客的连接：使用 VPN 的人会显示为 VPN 所在国家/地区，而无法确定位置的访客会被允许访问，而不是被拒之门外。即使您屏蔽了您所在的国家/地区，您在应用内的预览功能仍可正常使用。
• 每个连接的新对话数。 一个连接（实际上是一个家庭或办公室地址）每天可以在一个小部件上开启 20 次新对话。继续现有聊天的回头客不计入在内，只有全新的对话才计入。因此，试图通过不断发起新聊天来刷 AI 回复的脚本在 20 次后就会失效，而真实访客则完全不会察觉。如果许多人通过同一个连接访问您的网站（如校园、呼叫中心），请通过 REST API 使用 max_new_chats_per_ip_daily 提高该数值；0 可关闭此检查。
• 人工检查（可选）。 访客在发送第一条消息前需通过快速的 Cloudflare Turnstile 检查，因此脚本将完全无法发起聊天。大多数人无需点击任何内容；Cloudflare 仅在不确定时才会显示复选框。它使用您自己的免费 Turnstile 密钥，请参阅下方的 添加人工检查。
• 内置限制。 除此之外，每个浏览器会话在每分钟和每天可发送的消息数量上都有限制，并且当访客达到其 响应限制 下设置的 每次聊天 AI 消息上限 时，回答聊天的代理将停止回复。

这些操作都不会识别设备或个人：在访客选择聊天之前，小部件不会在访客的浏览器中存储任何内容（见上文），并且不存在指纹识别。

添加人工检查 (Cloudflare Turnstile) #

当机器人不断在您的网站上发起聊天，且上述设置不足以应对时，请开启此功能。该检查在访客发送第一条消息前运行一次。通过检查的访客可以在 24 小时内继续聊天而无需再次验证，任何返回之前对话的访客在检查前仍可阅读内容。

1. 登录您的 Cloudflare 账户（免费账户即可）并打开 Turnstile。
2. 点击 Add widget，为其命名，并添加您的聊天小部件运行的所有域名（例如 yourshop.com）。将小部件模式保持为 Managed。
3. 复制 Cloudflare 显示给您的 Site key 和 Secret key。
4. 在应用中，打开聊天小部件的 Manage 面板，开启 Human check before chatting，粘贴这两个密钥并保存。

预期效果：

• 在填入两个密钥之前，检查功能保持关闭状态，因此在没有密钥的情况下开启它永远不会将访客拒之门外。
• 如果访客未通过检查或未完成检查，他们的消息将不会发送，并会看到一个 Retry 按钮。
• 检查仅在您于 Cloudflare 中添加的域名上显示。在任何其他域名上，Cloudflare 都会拒绝它，因此该网站上的任何人都无法发送消息，请务必在开启前添加所有域名。
• 如果您的网站使用内容安全策略 (Content Security Policy)，请允许 https://challenges.cloudflare.com 用于脚本和框架，否则检查将无法加载。
• 这些密钥属于您自己的 Cloudflare 账户，且密钥永远不会发送到访客的浏览器。

安装说明 #

要将聊天组件添加到您的网站，请在您网站的 HTML 中添加一行代码。

1. 在文本编辑器中打开您网站的 HTML 文件。
2. 找到结束的 </body> 标签——这通常位于文件的末尾。
3. 将此行代码粘贴在 </body> 标签之前，以便页面的其余部分先加载：

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

4. 将 CONFIG_ID 替换为您唯一的配置标识符，该标识符显示在管理面板的渠道与嵌入部分。此标识符特定于您的账户，用于将组件连接到您的消息系统。

该代码片段不会拖慢您的网站速度：它是一个微小的加载器，且小组件本身会在后台下载，不会阻塞页面。如果您仍希望小组件在页面完全加载完成后再显示，可以将相同的 URL 包装成这样：

<script>
window.addEventListener('load', function () {
  var s = document.createElement('script');
  s.src = 'https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID';
  s.async = true;
  document.body.appendChild(s);
});
</script>

如果您想要延迟的是小提示气泡而非小组件的加载，请使用上述“行为”部分中的主动弹出气泡延迟设置——无需编写代码。

在 Shopify 上安装 #

1. 在您的 Shopify 管理后台，前往 在线商店 > 主题。
2. 在标记为当前（已发布）的主题上，点击 … 按钮并选择 编辑代码。编辑草稿或主题副本不会对您的在线商店产生任何影响。
3. 打开 layout/theme.liquid 并滚动到底部附近的闭合 </body> 标签处。
4. 将您的安装代码行粘贴在 </body> 正上方，然后点击 保存：

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

如果您在安装代码行包含 defer 之前安装了小部件，Shopify 的代码编辑器会在其下方显示红色下划线。该下划线是 Shopify 代码检查器针对没有 defer 或 async 的脚本行发出的警告，而非错误：主题仍然可以保存，小部件也能正常工作。按照上述方式添加 defer 可以消除下划线，且不会改变小部件的任何行为，因此无需在其他站点重新安装。

以下是实现聊天组件后您的 HTML 文件应呈现的完整示例：

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your existing website content would be here -->

    <!-- Chat Widget Integration -->
    <script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>
</body>
</html>

在页面中内嵌（高级） #

如果您希望聊天作为页面的一部分显示（例如在专门的“联系我们”部分、帮助选项卡或侧边栏中），而不是作为角落里的浮动气泡，请在管理面板中将嵌入代码片段切换为内嵌，并复制内嵌代码片段。

它看起来像这样：

<div data-chat-widget="CONFIG_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

<div> 是挂载点——聊天面板会在其中渲染并填满其尺寸。你可以随意设置该 div 的样式（赋予固定高度、将其放入 flex 容器、放置在网格单元格中等），聊天面板将随之调整。

即使你嵌入了多个聊天小部件，页面上也只需要 一个 <script> 标签。脚本会扫描页面上的每一个 <div data-chat-widget="…">，并在其中挂载一个聊天面板。

何时选择内嵌式与浮动式：

• 浮动气泡 适合作为全站通用的“需要帮助？”按钮。
• 内嵌式嵌入 适合聊天窗口需要出现在特定位置（如支持页面、知识库侧边栏、应用内帮助标签页）并作为页面原生部分呈现的情况。

内嵌式嵌入复用了与浮动气泡相同的配置（徽标、开场白、潜在客户捕获、引导问题等），因此你无需重复设置。

在其他人的网站上显示小部件 #

您可以在您无法控制的网站上显示正在运行的聊天小部件 — 无需代码，也无需访问对方的网站。这是向潜在客户展示助手在他们自己的页面上看起来是什么样子的最快方式。

1. 打开“管理”面板并滚动至 Channels & Embed（渠道与嵌入）。
2. 在 Client demo link（客户演示链接）中，输入网站地址（例如 www.theircompany.com）。
3. 可选：在该字段下方，选择应在此演示中进行回复的 Agent（智能体），例如您可以选择一个根据潜在客户自身网站构建的智能体，以便它能介绍其服务、价格和常见问题解答。保持为 Account default（账户默认）即可使用您常规的聊天小部件路由。
4. 点击 Create link（创建链接）。链接将自动为您复制，并出现在字段下方的列表中，同时显示 Copy（复制）和 Open（打开）按钮以及它所使用的智能体。
5. 将该链接发送给您想要展示的对象。

打开该链接会加载目标网站，并将您的聊天小部件悬浮在上方，效果与实际安装时完全一致。任何拥有该链接的人都可以打开它 — 无需登录。

几点值得注意的事项：

• 演示中的聊天是真实的。 访客在演示中发送的消息会到达您的收件箱，并由您的坐席回复，且会像其他任何对话一样消耗积分。
• 页面无品牌标识。 它仅显示对方的网站和您的插件，不包含其他任何内容。
• 某些网站无法被嵌入。 一些网站（如银行、大型零售商或具有严格安全设置的网站）会阻止其他页面显示它们。在这种情况下，链接仍然有效：它会显示一个中性的模拟浏览器窗口，而不是真实的网站，但您的插件仍会在上方正常运行，从而确保演示功能不受影响。
• 它不会更改对方的网站。 无需安装，也无需修改任何内容——演示仅存在于该链接中。
• 演示结束后关闭链接。 点击列表中链接旁边的关闭并确认。此后，任何打开该链接的人都会看到页面提示该链接已被关闭。您的插件和其他演示链接将继续工作。已关闭的链接无法重新开启；请创建一个新的链接。
• 2026 年 9 月 25 日之前复制的链接。 在列表功能出现之前创建的演示链接不会显示在列表中。它们将持续有效，直到您点击列表下方的关闭这些链接，这将一次性关闭所有此类链接（点击重新开启它们可撤销此操作）。

如果不指定客服，演示链接将使用账户的默认路由，无论“将这些聊天路由至”设置为何。如果选择了客服，来自该链接的每条聊天都会分配给该客服并由其回复。小部件将保留其自身的外观、名称和开场白。该链接将其携带为 &agent=AGENT_ID；手动将此参数添加到旧链接中也有效（请使用 &，不要使用 ?，因为链接中已经包含一个 ?）。

如果您之后删除了演示链接所使用的智能体，该链接仍可继续使用：其聊天内容将转为使用您的账户默认路由，且列表中会在其旁边显示“deleted agent, uses the default”（智能体已删除，使用默认设置）。删除作为聊天小部件默认设置的智能体，不会影响已固定到其他智能体的链接。

分享聊天直接链接 #

有时没有可放置小部件的网站 — 您可能希望直接给某人一个链接，让他们立即与您的助手交谈。每个聊天小部件都有一个：

1. 打开“管理”面板并滚动到 渠道与嵌入。
2. 找到 分享链接（位于客户演示链接下方）。
3. 点击 复制 以获取链接，或点击 打开 以亲自尝试。

打开该链接只会显示您的助手，并填满整个屏幕 — 后面没有网站，无需先点击气泡，也无需安装任何东西。您可以将其放在 Instagram 个人简介、传单上的二维码、电子邮件签名或发送给潜在客户的 WhatsApp 消息中。

共享链接遵循您聊天小部件的默认路由。若要指定特定客服，请在链接末尾添加 ?agent=AGENT_ID；来自该链接的每条聊天都会分配给该客服并由其回复，同时页面将保留您小部件的名称和开场白。

几点值得注意的事项：

• 来自链接的聊天是真实的。 它们会到达您的收件箱，由您的坐席回答，并且像任何其他对话一样消耗信用额度。
• 该页面不带有我们的品牌标识。 它只显示您的助手，且不会出现在搜索结果中。
• 它在您自己的地址上运行。 如果您的提供商在他们自己的域名上运行该应用程序，该链接也会使用该地址，因此不会显示任何陌生的内容。
• 每个浏览器、每个链接对应一位访客。 无论谁打开它，在该浏览器中都保持相同的身份，因此稍后返回时会继续之前的对话，而不是开始一个新的陌生人对话。不同的浏览器或不同小部件的链接代表不同的访客。

将不同页面发送给不同坐席 #

默认情况下，通过您的小部件进来的每场聊天都由同一位坐席处理。您可以针对每个页面覆盖此设置，这样访问您定价页面的访客将与销售坐席交谈，而访问您帮助页面的访客将与支持坐席交谈，所有这些都通过同一个聊天小部件完成。

获取代码有两种方式：

• 从坐席处设置。 在 AI 坐席 页面上，点击该行上的 </> 按钮，或打开坐席并转到其 入口点 选项卡。无论哪种方式，您都会获得一个已指向该坐席的、可直接粘贴的代码片段。

  坐席的 入口点 (Entry points) 选项卡还有一个 网站聊天小部件 (Website chat widget) 面板，显示该坐席当前正在处理的网站聊天数量。来自嵌入的聊天会直接到达坐席，因此你不需要为它们创建入口点规则——即使没有任何规则的坐席也能回答其嵌入的聊天。

  </> 按钮仅在处于活动状态的坐席上显示。已暂停的坐席会收到聊天但不会回复，因此该选项在您重新开启之前是隐藏的。坐席无需设置渠道 — 坐席可以从任何渠道接听聊天。

• 从小部件设置中设置。 在聊天小部件的 设置 → 渠道 → 管理 中，设置 将这些聊天路由至，然后复制下方的代码片段。更改下拉菜单会自动重写代码片段。

浮动式代码片段在地址中携带了目标信息：

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID?agent=AGENT_ID" defer></script>

内嵌式代码片段则将目标信息携带在 <div> 上，因此一个页面可以容纳多个指向不同位置的聊天：

<div data-chat-widget="CONFIG_ID" data-agent="AGENT_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

在营销活动（campaigns）功能停用前复制的代码片段中包含 ?campaign= 或 data-campaign=。它们将继续有效，因此无需重新粘贴。

几点值得注意的事项：

• 请使用复制按钮，而不是手动输入 ID。如果 ID 与您账户上的坐席不匹配，聊天仍然有效，但会回退到您的默认路由。
• 已经在对话中的访客将保持与初始坐席的对话，即使他们随后进入了指向其他坐席的页面。这可以防止对话中途更换“人设”。
• 页面特定的目标设置优先级高于您的账户默认设置和关键字触发器。

告知小部件访客身份（高级） #

如果您将聊天小部件放置在会员专区、客户门户或用户已登录的应用程序中，您的网站已经知道他们的身份。您可以将其传递给小部件，这样访客就不必再次输入他们已经提供过的信息，您的 AI 也可以利用您已掌握的关于他们的信息。

在小部件脚本之前添加一个小的设置代码块：

<script>
  window.chatWidgetSettings = {
    visitor: {
      id: "12345",
      name: "Maria",
      email: "maria@example.com",
      phone: "+391234567890"
    },
    data: {
      plan: "Professional",
      customer_since: "2024",
      last_order: "A-2291"
    }
  };
</script>
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

您的页面应在服务器端填充这些值，具体取决于当前登录的用户。

若要同时保存姓氏，请在 visitor 块（内嵌嵌入时为 data-visitor-last-name）中将 last_name 添加到 name 旁边。这是可选的：无论是否开启收集姓氏，姓名和电子邮件仍足以跳过表单。

会发生两件事：

• 跳过“开始之前…”表单。 提供姓名和电子邮件后，访客将直接进入对话，这些详细信息将保存到他们的联系人信息中，就像他们自己输入的一样。
• data 下的所有内容都会传递给您的 AI。 您在此处放入的任何内容（如套餐、订单号、续订日期、信用余额、席位数量等）都将成为 AI 对该用户了解的一部分，因此它可以回答“我的套餐什么时候续订？”之类的问题，而无需先询问他们的身份。使用对您有意义的任何字段名称；它们会显示在联系人的“自定义字段”下。最多支持 20 个值，随每条消息实时发送，因此如果套餐在对话中途发生变更，AI 也能看到新的信息。

对于内嵌式嵌入，您可以将相同的信息放在 <div> 上，这在单个页面包含多个聊天窗口时非常方便：

<div data-chat-widget="CONFIG_ID"
     data-visitor-name="Maria"
     data-visitor-email="maria@example.com"
     data-visitor-data='{"plan":"Professional"}'
     style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

如果您的网站仅在页面加载后才知道访客是谁（例如，登录无需重新加载页面的单页应用程序），请在获取详细信息时调用此方法，小部件会自动更新：

<script>
  window.chatWidget.setVisitor({
    visitor: { id: "12345", name: "Maria", email: "maria@example.com" },
    data: { plan: "Professional" }
  });
</script>

几点值得注意的事项：

• 如果两个不同的人在同一台电脑上登录，第二个人会开启一个新的对话，而不是看到第一个人的聊天记录。小部件会检测到人员变更并自动重置。
• 就其本身而言，这仅用于上下文，而非用于登录。对话仍像往常一样保持独立，因此传递 id 并不会让任何人打开他人的聊天记录，而在不同设备或浏览器上使用的人也会开启新的对话。若要在不同设备间同步对话，请按接下来所述对 id 进行签名。
• 这是可选的。普通公共页面上的小部件不需要这些设置，其行为与之前完全一致。

在任何设备上恢复同一对话（已登录访客 ID） #

如果您的客户拥有账户，您可以让他们的聊天记录跟随他们：在手机上登录，在笔记本电脑上继续，这在您的收件箱中是同一个联系人的同一个对话，AI 也了解之前所说的一切。为此，Your AI Connector 需要证明访客确实是您页面所声称的那个人，否则任何人都可以将客户编号输入浏览器并读取该客户的聊天记录。该证明是您在服务器上计算出的签名。

1. 在小部件的 Manage 面板中，找到 Channels & Embed 下的 Signed-in visitors，然后点击 Generate secret。复制身份密钥。请务必将其仅保存在服务器上；切勿将其放入页面本身。

2. 当您的服务器为已登录的客户渲染页面时，请使用该密钥计算客户 ID 的 HMAC-SHA256，并将其转换为小写十六进制字符串：

// Node.js
const hash = require("crypto").createHmac("sha256", IDENTITY_SECRET).update(customerId).digest("hex");

// PHP
$hash = hash_hmac('sha256', $customerId, IDENTITY_SECRET);

# Python
import hmac, hashlib
hash = hmac.new(IDENTITY_SECRET.encode(), customer_id.encode(), hashlib.sha256).hexdigest()

3. 将 ID 和哈希值放入设置块中，紧邻您已经传递的姓名和电子邮件：

<script>
  window.chatWidgetSettings = {
    visitor: {
      id: "12345",
      hash: "3f2a…e91c",
      name: "Maria",
      email: "maria@example.com"
    }
  };
</script>
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

内联嵌入采用与 <div> 上的 data-visitor-hash 相同的值，而 window.chatWidget.setVisitor({ visitor: { id, hash } }) 适用于无需页面重新加载即可登录的应用。

签名验证通过后会发生什么：

• 客户的聊天记录存储在他们的账户下，而不是浏览器下，因此在他们登录的每台设备和每个浏览器上都是同一个对话，在您的收件箱中也对应同一个联系人。
• 他们之前的消息会在新设备上加载，AI 会从他们上次中断的地方继续。
• 如果签名错误，小部件会静默地恢复为之前的行为，即作为普通的按浏览器区分的聊天，并在浏览器控制台中打印原因，以便开发人员查看。您的访客永远不会看到错误。
• ID 会按照您发送的原样进行比较，因此请对您作为 id 传递的相同值进行签名，并在任何地方都为同一个人使用相同的 ID。

需要了解两点：

• 在管理面板中点击 重新生成 (Regenerate) 将为您提供一个新的密钥。在您的服务器使用新密钥之前，仍使用旧密钥签名的页面将回退为正常的按浏览器区分的聊天。现有的对话会被保留；它们与客户的 ID 绑定，而不是与密钥绑定。
• 某人在登录前作为匿名访客进行的对话将保持为独立的聊天。基于账户的对话从他们登录后发送的第一条消息开始。

通过您自己的代码更改小部件设置 (API) #

小部件 管理 (Manage) 面板上的所有内容也可以通过 REST API 进行更改，如果您管理多个网站或希望自动为客户关闭附件按钮，这将非常方便。发送 PATCH 到 https://api.youraiconnector.com/v1/chat-widget-configs/CONFIG_ID，并在其中包含您的 API 密钥以及您想要更改的字段——例如 {"show_upload_button": false} 可隐藏附件按钮，{"show_emoji_button": false} 可隐藏表情符号选择器，{"launcher_icon": "chat-dots"} 可更换启动器图标。CONFIG_ID 是与您的嵌入脚本中相同的标识符。可接受字段的完整列表（名称、开场消息、颜色、启动器图标、允许的域名、访客信息表单、隐私声明、主题、圆角和字体样式）位于 API 参考 的 聊天小部件 (Chat Widget) 下。网站会在下次页面加载时获取这些更改。

安装后的预期效果 #

将脚本添加到您的网站后，聊天小部件会自动在网站角落（默认在右下角）创建一个聊天按钮。当用户滚动页面时，该小部件会保持固定位置，确保始终可以访问。

当访客点击此按钮时，它会展开为一个完整的聊天窗口，访客可以在其中开始对话，并显示您的开场白。如果开启了“收集访客信息”，则在访客输入内容前，会先弹出一个小表单，要求他们提供姓名和电子邮件（以及可选的电话）。

聊天界面会自动适应不同的屏幕尺寸，因此在桌面端和移动端设备上都能无缝运行。

测试您的实现 #

将小部件添加到您的网站后，请测试其是否正常工作：

1. 在浏览器中打开您的网站。
2. 点击聊天按钮以打开小部件。
3. 发送一条测试消息，并确认您收到了回复。
4. 在不同的设备或浏览器上重复此操作，以确认它在任何地方都能正常工作。

如果聊天小部件未在您的网站上显示，请检查以下内容：

1. 确保您已将 CONFIG_ID 替换为您实际的配置标识符。
2. 确保脚本标签放置在闭合 </body> 标签之前。
3. 检查代码是否存在拼写错误。
4. 在 Shopify 上，确保您编辑的是已发布的主题并点击了 保存。在草稿或复制的主题中所做的编辑不会同步到您的在线商店。

在企业防火墙后 #

如果小部件在公共网络下可以加载，但在办公网络下的员工端无法加载，那么几乎可以确定是网络屏蔽了其加载来源的域名。请要求你的 IT 团队在 443 端口通过常规 HTTPS 协议允许以下内容：

• 嵌入代码片段中的域名 —— 即你从“管理”面板复制的 <script src="..."> 行中的地址。
• api.youraiconnector.com —— 小部件也会向此处发送消息。

无需开放其他任何内容：不需要额外的端口，也不需要入站规则。如果在此之后小部件仍然无法显示，请在页面上打开浏览器的开发者控制台并将报告内容发送给我们——被拦截的请求会指明被拒绝的域名，这通常就是问题的全部答案。