Chat Widget
Add an AI-powered shopping chat to your store with a single line of code. The widget automatically adapts to your store's colors and works on all devices.
Info
The widget can be customized extensively.
🔑 API Key Security
The widget runs in the browser, so you must use a Public Key (starts with pk_live_). Never expose your Private Key (sk_live_) in client-side code. Private keys are for server-side only.
Installation
Choose the installation method that fits your project:
index.html
html
<script src="https://cdn.aicommerce.dev/widget.min.js">script>
<script>
AICommerceWidget.init({
apiKey: 'YOUR_API_KEY',
storeId: 'YOUR_STORE_ID',
// Widget appears in bottom-right corner by default
});
script>Customization
Customize the widget's appearance and behavior to match your brand:
config.ts
typescript
AICommerceWidget.init({
apiKey: 'YOUR_API_KEY',
storeId: 'YOUR_STORE_ID',
// Display Mode
displayMode: 'widget', // 'widget' (floating) or 'embedded' (inline)
// Positioning (widget mode only)
position: 'bottom-right', // or 'bottom-left'
zIndex: 9999,
// Theming (automatically uses store's primaryColor if not set)
theme: 'auto', // 'light', 'dark', or 'auto'
primaryColor: '#6366f1', // Override store's color
// Branding
botName: 'Shopping Helper',
welcomeMessage: 'Hi! How can I help you find the perfect product?',
buttonText: '💬',
// Event callbacks
onOpen: () => console.log('Chat opened'),
onClose: () => console.log('Chat closed'),
onProductClick: (product) => {
window.location.href = product.url;
},
// Custom Add to Cart handler (for non-Shopify stores)
onAddToCart: async (product) => {
// Example: WooCommerce cart integration
await fetch('/wp-json/wc/store/cart/add-item', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id: product.id, quantity: 1 })
});
// Or your custom cart logic
// cart.addItem({ id: product.id, name: product.name, price: product.price });
alert('Added to cart: ' + product.name);
},
// Custom Buy Now handler
onBuyNow: async (product) => {
window.location.href = '/checkout?product=' + product.id;
},
onMessage: (message, response) => {
console.log('User asked:', message);
console.log('AI replied:', response.reply);
},
});Tip
Use the configuration options to match your brand.
Configuration Options
| Field | Type | Default | Description |
|---|---|---|---|
| apiKey | string | - | Your API key (required) |
| storeId | string | - | Your Store ID (required) |
| displayMode | 'widget' | 'embedded' | 'widget' | Display mode: floating widget or inline embedded container |
| container | string | HTMLElement | - | Container element or CSS selector for embedded mode |
| height | string | '500px' | Height of the chat container in embedded mode |
| position | 'bottom-right' | 'bottom-left' | 'bottom-right' | Widget position on screen |
| theme | 'light' | 'dark' | 'auto' | 'auto' | Theme mode (auto follows system preference) |
| primaryColor | string | Store color | Brand color (overrides store setting) |
| botName | string | Store setting | Chat assistant name |
| welcomeMessage | string | Store setting | First welcome message |
| hideLauncher | boolean | false | Hide the default bubble button |
| predefinedQuestions | string[] | Store setting | docs.tableDescriptions.predefinedQuestions |
| showAddToCart | boolean | true | Whether to show the Add to Cart button |
| showBuyNow | boolean | true | Whether to show the Buy Now button |
| onAddToCart | function | - | Custom handler for Add to Cart action |
| onBuyNow | function | - | Custom handler for Buy Now action |
Instance Methods
| Method | Description |
|---|---|
| open() | Opens the chat window |
| close() | Closes the chat window |
| toggle() | Toggles the chat window state |
| sendMessage(msg) | Sends a message programmatically |
| updateConfig(opts) | Updates widget configuration |
| destroy() | Removes the widget from the page |