Vocantly小部件
一、 可嵌入的支持聊天小部件 建立在无头的基础上 @vocantly/sdk。一个
<script> 渲染一个浮动的聊天气泡+面板；你的访客与人工智能聊天
代理)与零UI工作在您这边。
dist/vocantly-widget.js 是一个独立的文件(~63 KB) - SDK，它的深度，和
UI都捆绑在一起。没有导入映射，没有主机的构建步骤。
安全模型（重要）
小部件在浏览器中运行，因此它只保存一个 SDK令牌 (作用域为一个应用程序+一个 游客,短暂的)。你的 API密钥+秘密永远不会触及浏览器。 流:
Your backend (holds API key) Browser (this widget)
POST /apps/:id/support-sessions ── token + conversation_id ──▶ VocantlyWidget.init({...})
(X-Api-Key + X-Api-Secret)
您的服务器调用供应端点，然后只执行手动操作 { token, conversation_id } 到页面。
安装
选项A -脚本标签（任何网站，通过CDN）：
<!-- unpkg / jsDelivr serve the bundled IIFE; global: VocantlyWidget -->
<script src="https://unpkg.com/@vocantly/widget"></script>
<!-- pin a version: https://unpkg.com/@vocantly/[email protected] -->
选项B - npm (React / Vue / Next / bundlers)：
npm install @vocantly/widget
import { init } from '@vocantly/widget';
init({ wsUrl, token, conversationId, /* … */ });
两者都提供了捆绑在零对等依赖中的SDK + deps。用法都是一样的：
<script src="https://unpkg.com/@vocantly/widget"></script>
<script>
VocantlyWidget.init({
wsUrl: 'wss://your-realtime/ws',
token: 'SDK_TOKEN_FROM_YOUR_BACKEND',
conversationId: 'CONVERSATION_ID_FROM_YOUR_BACKEND',
apiUrl: 'https://your-backend/api/v1', // optional — enables message history
title: 'Support',
subtitle: 'We reply in a few minutes',
primaryColor: '#195EFF',
position: 'bottom-right', // or 'bottom-left'
greeting: 'Hi! 👋 How can we help?',
autoOpen: false,
// Optional pre-chat contact capture (needs apiUrl):
collectContact: true, // ask name + email before chatting
requireEmail: false, // if true, email is mandatory to start
contactPrompt: 'Before we start — how can we reach you?',
});
</script>
您的后端（对供应的一次调用）
// server-side — keep the secret here
const r = await fetch(`${BASE}/apps/${APP_ID}/support-sessions`, {
method: 'POST',
headers: { 'X-Api-Key': PUBLIC_KEY, 'X-Api-Secret': SECRET_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ external_user_id: yourUserId, name, email }),
});
const { token, conversation_id } = (await r.json()).data; // hand these to the browser
没有后端?只使用您的公钥匿名嵌入
对于一个静态的登陆页面 未经身份验证的访问者和没有服务器,使用 publicKey 而不是
token/conversationId。小部件自己提供一个匿名会话-在浏览器中没有秘密：
<script src="https://unpkg.com/@vocantly/widget"></script>
<script>
VocantlyWidget.init({
publicKey: 'pk_…', // your app PUBLIC key (safe to expose)
wsUrl: 'wss://ws.vocantly.com/ws',
apiUrl: 'https://api.vocantly.com/api/v1', // required in this mode
collectContact: true,
});
</script>
一个先决条件-允许您的网站的来源。 默认情况下，匿名嵌入是关闭的。添加你
域(s)应用程序的 allowed_origins （仪表板，或通过API）：
PATCH /apps/:id { "allowed_origins": ["https://acme.com", "https://www.acme.com"] }
小部件生成 稳定访客id （localStorage）和缓存 {token, conversationId} 所以一个
重新加载将恢复相同的对话。请求在服务器端进行初始检查，并且速率有限。
提供 要么
publicKey(匿名) 或者token+conversationId(backend-provisioned)。
API
| 呼叫 | 效果 |
|---|---|
VocantlyWidget.init(opts) | Mount + connect。返回 { open, close, send, destroy }. |
VocantlyWidget.open() / .close() | 切换面板。 |
VocantlyWidget.destroy() | 断开连接并从DOM中删除。 |
聊天前联系人捕获
与 collectContact: true时，小部件会询问访问者的姓名+（可选）电子邮件地址
聊天，并保存到他们的客户档案通过 PATCH /sdk/customers/me (经
SDK令牌-浏览器中没有秘密)。然后代理在收件箱中看到访问者的联系方式。
需要 apiUrl 待设置。使用 requireEmail: true 让电子邮件成为强制性的。
构建
npm run build # → dist/vocantly-widget.js (minified IIFE, global VocantlyWidget)
npm run build:dev # non-minified + sourcemap
构建包 ../vocantly-js-sdk/dist/index.js。如果重新构建SDK，则重新构建小部件。
演示
npm run serve:demo # serves this folder on :5173
# open http://localhost:5173/ (redirects to the demo)
避免端口Chrome块为“不安全”（例如5060 = SIP→）
ERR_UNSAFE_PORT）. 5173很安全。 演示是一个模拟的业务页面。输入工作空间所有者的电子邮件/密码+ a 开发 应用程序ID 并点击 引导 -透过/apps/:id/support-sessions(dev login代表你的 后端)并安装小部件。需要后端:3001实时运行:8080，和应用程序有 启用bot +一个活跃的FAQ.
已知的限制
Bot回复目前是实时交付的，但是 不坚持 服务器端，所以它们不会出现在 重新加载时的消息历史记录（客户/代理消息）。持久化bot消息是后端后续工作。