Tham số trang & sự kiện
Gửi ngữ cảnh màn hình cho trợ lý và nhận sự kiện nghiệp vụ (đơn đã tạo, chuyển nhân viên…).
screen_context — trợ lý biết người dùng đang ở đâu
Gửi kèm thông tin trang hiện tại để trợ lý không phải hỏi lại: tên, số điện thoại, cửa hàng, sản phẩm đang xem…
const vb = Voicebox.init({
key: 'vb_xxx',
screenContext: { store_id: 'S01', phone: '0912345678', full_name: 'Nguyễn An', screen: 'product_detail', product_sku: 'SP001' },
});
// trang đổi ngữ cảnh — áp dụng từ lượt sau; null = xoá key
vb.setScreenContext({ store_id: 'S02' });Khai báo trên thẻ script cũng được (kebab-case tự đổi sang snake_case):
<script src="https://voicebox.aivigo.tech/widget/v1/voicebox.js" data-key="vb_xxx" data-screen-context-store-id="S01" async></script>Với Core API, gửi trường screen_context trong body /agent/process.
Quy tắc
| Quy tắc | Giá trị |
|---|---|
| Tên key | snake_case, ^[a-z][a-z0-9_]{0,39}$ |
| Số key | Tối đa 30 |
| Kích thước | Mỗi giá trị ≤ 2 KB, tổng ≤ 8 KB, lồng ≤ 3 cấp |
| Gộp theo phiên | Key mới ghi đè, null xoá key |
| Sai quy tắc | 422, errors[].field = "screen_context.<key>" |
Không đưa mật khẩu, token, số thẻ vào screen_context. Tham số quyết định quyền/giá (mã khách, hạn mức) phải được ký ở server
bằng identity secret và gửi kèm screenContextSig.
// ký tham số signed (server)
const canonical = (o) => JSON.stringify(Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : 1))));
const screenContextSig = createHmac('sha256', IDENTITY_SECRET).update(canonical({ customer_id: 'C123' })).digest('hex');Sự kiện đầu ra
Trợ lý phát sự kiện khi có kết quả nghiệp vụ để trang của bạn phản ứng:
vb.on('order.created', ({ order_id, total }) => location.assign('/orders/' + encodeURIComponent(order_id)));
vb.on('conversation.handoff', () => openSupportChat());
vb.on('event', ({ name, data }) => console.log(name, data)); // mọi sự kiện- REST/SSE: JSON trả về có
events: [{ name, data }]; luồng SSE cóevent: client_eventngay trướcreply. - WebView: nhận qua cầu nối native
{ source: 'voicebox', type: 'event', data: { name, data } }. - Cần kết quả tin cậy ở backend (không qua trình duyệt)? Dùng Webhook.