Nhúng Voicebox trên website
Thẻ script, khung chat cố định, iframe, JS API và React/Next.js.
Voicebox là khung chat + giọng nói dựng sẵn. Bạn chỉ cần khoá công khai vb_… (lấy ở Cổng đối tác → Voicebox & Widget)
và khai báo origin (tên miền) của trang trong danh sách được phép.
Bong bóng chat (cách nhanh nhất)
Dán trước thẻ đóng body:
<script src="https://voicebox.aivigo.tech/widget/v1/voicebox.js" data-key="vb_xxx" async></script>Góc phải màn hình xuất hiện nút chat. Người dùng gõ hoặc bấm micro để nói; trợ lý trả lời kèm thẻ sản phẩm, nút xác nhận…
Thuộc tính tuỳ chọn trên thẻ script:
| Thuộc tính | Giá trị |
|---|---|
data-mode | floating (mặc định), inline, fullscreen |
data-container | CSS selector khi inline |
data-theme | light, dark, auto |
data-locale | vd. vi-VN, en-US |
data-base-url | Khi bạn tự host file voicebox.js ở nơi khác |
Inline và Web Component
Khung chat nằm cố định trong trang (trang hỗ trợ, dashboard):
<div id="ai-chat" style="height: 640px"></div>
<script src="https://voicebox.aivigo.tech/widget/v1/voicebox.js"
data-key="vb_xxx" data-mode="inline" data-container="#ai-chat" async></script>Hoặc dùng Web Component:
<script src="https://voicebox.aivigo.tech/widget/v1/voicebox.js" async></script>
<voicebox-chat key="vb_xxx" mode="inline" style="display:block;height:640px"></voicebox-chat>Widget vẽ trong Shadow DOM — CSS của trang bạn không làm vỡ widget và ngược lại.
iframe
Dùng khi CMS không cho chèn script:
<iframe src="https://voicebox.aivigo.tech/widget/v1/frame.html?key=vb_xxx&mode=fullscreen"
style="width:400px;height:640px;border:0;border-radius:16px"
allow="microphone; autoplay; clipboard-write"></iframe>iframe chỉ hiển thị trên các origin được phép. Trang của bạn nhận sự kiện qua window.addEventListener('message', …)
(event.data.source === "voicebox") và điều khiển widget bằng:
iframe.contentWindow.postMessage({ source: 'voicebox-host', type: 'send', data: 'xin chào' }, '*');JS API
const vb = Voicebox.init({
key: 'vb_xxx',
mode: 'floating', // floating | inline | fullscreen
container: '#ai-chat', // khi inline
user: { ref: 'kh001', name: 'An', hash: '<ký từ server>' }, // bỏ qua nếu là khách vãng lai
theme: 'auto',
appearance: { brand_color: '#E11D48' },
});
vb.on('ready', () => {}); // đã nạp cấu hình
vb.on('reply', (r) => {}); // r.status, r.agent, r.reply.text, r.reply.ui
vb.on('handoff', (r) => {}); // cần chuyển nhân viên — mở kênh CSKH của bạn
vb.on('error', (e) => {}); // { code, status, message }
vb.on('session', (s) => {}); // { session_id }
vb.open(); vb.close(); vb.toggle();
vb.send('Khuyến mãi hôm nay?'); // gửi thay người dùng
vb.identify({ ref, name, hash }); // sau khi đăng nhập; identify(null) khi đăng xuất
vb.reset(); // cuộc trò chuyện mới
vb.destroy();Có thể gọi Voicebox.open() / Voicebox.send() trước khi script tải xong — lệnh được xếp hàng.
Danh tính user.hash xem Danh tính người dùng.
Lịch sử hội thoại
vb.openHistory();
const { data } = await vb.listConversations({ limit: 20 });
await vb.openConversation(data[0].id);
vb.on('conversation', ({ session_id, action }) => {}); // open | new | deleteĐã identify ⇒ lịch sử theo người dùng trên mọi thiết bị; ẩn danh ⇒ lịch sử theo trình duyệt.
React / Next.js
'use client';
import { useEffect } from 'react';
export function AiChat({ user }: { user?: { ref: string; name?: string; hash?: string } }) {
useEffect(() => {
let vb: any;
const s = document.createElement('script');
s.src = 'https://voicebox.aivigo.tech/widget/v1/voicebox.js';
s.async = true;
s.onload = () => { vb = (window as any).Voicebox.init({ key: 'vb_xxx', user }); };
document.body.appendChild(s);
return () => { vb?.destroy(); s.remove(); };
}, [user?.ref]);
return null;
}Content-Security-Policy
Nếu trang có CSP, cho phép domain Voicebox:
script-src https://voicebox.aivigo.tech;
connect-src https://voicebox.aivigo.tech;
img-src https://voicebox.aivigo.tech data:;
media-src data: blob:;
worker-src blob:;
frame-src https://voicebox.aivigo.tech; # chỉ khi dùng iframeKiểm tra sau khi nhúng
- Mở trang từ một origin không được phép ⇒ widget không tải (
403 origin_not_allowed). - Đăng xuất ⇒ gọi
identify(null)để không lộ lịch sử của người trước. - Thử nhanh không cần trang của bạn:
https://voicebox.aivigo.tech/widget/v1/demo.html?key=vb_xxx.