This chatbot widget was developed for Agile Alpaca clients who have used our AI-agent integration services in their online stores. It’s designed for commercial websites to help visitors quickly get answers to their questions and place orders.
Last update: April 3, 2026.
- bsign-store.com - Manufacturer of custom door signs and modern door numbers made from metal, wood, and acrylic for homes, offices, apartments, and hotels.
- bsign-store.com.ua - Ukrainian storefront of BSign focused on interior door signs and room numbers for homes, offices, and hospitality spaces.
- lemap.co - Store focused on travel-themed wall maps, especially national park maps and related decor/sign products.
- dfadecor.com - Interior decor shop with reusable wall stencils, mirror strips, and imprint tools for decorative wall finishing.
- evenwood.com.ua - Ukrainian handmade wooden decor and home-organization products, including planters, shelves, and shoe storage.
- ndukraine.com - Ukrainian goods store selling embroidered clothing, accessories, and home decor with handmade focus.
- buzzcrafts.art - Gift store centered on anniversary gifts by year and milestone-based present ideas.
- Token-based theming (
themepresets +themeTokensoverrides + CSS variables). - Animated popup window – the chat window is anchored to the bottom-right corner and opens/collapses with smooth animation.
- Open button + message badge
- External open trigger by element
id - Flexible widget positioning (screen presets, fixed coordinates, or near trigger)
- Style isolation by default (Shadow DOM mount) to avoid host CSS collisions.
- Welcome message
- Previous dialogue restoration
- Quick-reply prompts (chat prompts)
- Page context (pageContext) – lets you run arbitrary scripts (e.g., auto-show the chat or display a personalized message) once a visitor has spent timer ms on a specific pathname.
- Full control via context object – the execPageContext function provides external code with a complete set of setters (open, messageOptions, input, promptsOptions) plus a scrollToBottom method, simplifying integration with analytics or business logic.
- Input with Shift+Enter support – pressing Enter sends a message; Shift+Enter inserts a newline.
- Configurable input position - place input on top and header on bottom with props.
- Automatic scroll to the latest message
- Responsive design
- Full-page context handling – ability to send the entire page context to the server along with the user’s message.
apiBaseUrl must point to a specific public chat endpoint.
The widget uses the same URL for both read/send operations and sends requests with withCredentials: true.
- Method:
GET - Purpose: load existing dialog and create session (if cookie does not exist yet)
- Response shape:
{
"data": {
"sessionUuid": "uuid",
"createdAt": "ISO date",
"messages": [
{
"id": 1,
"text": "Hello",
"type": "INPUT",
"sentAt": "ISO date",
"usage": 10
}
]
}
}- Method:
POST - Body:
{
"text": "User message"
}- Response shape:
{
"data": {
"sessionUuid": "uuid",
"input": {},
"output": {
"text": "Bot reply"
}
}
}- Method:
OPTIONS - Purpose: browser preflight for cross-origin
POSTwith credentials
Minimal required CORS headers in API response:
Access-Control-Allow-Origin: <exact widget origin>Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET,POST,OPTIONSAccess-Control-Allow-Headers: Content-Type(or requested headers)
<head>
<!-- ... -->
</head>
<body>
<!-- ... -->
<button id="open-chatbot-btn">Open chat</button>
<div id="chatbot"></div>
<script src="https://cdn.jsdelivr.net/npm/ai-chatbot-widget@latest/dist/chatbot-widget.iife.js"></script>
<script>
const greeting = 'Hello! 👋 I’m the AI assistant.'
const contactUsMessage = `To get in touch with our manager, please leave your email address 📧, WhatsApp, or phone number 📱.
We'll get back to you during our business hours 🕖 7:00 a.m. – 4:00 p.m. CST.
Thank you for reaching out! 💬`
const chatPrompts = [
'I want a custom sign',
'I want to track my order',
'What are production and delivery times?',
'What are your shipping and refund policies?',
'I have problem with my order'
]
ChatbotWidget.mountChatbotWidget("#chatbot", {
apiBaseUrl: 'https://api.example.com',
greeting,
chatPrompts,
theme: {
preset: 'boring',
tokens: {
headerBackground: 'linear-gradient(90deg, #0f172a, #1e293b)',
openButtonBackground: '#0f172a',
openButtonColor: '#ffffff',
badgeBackground: '#f97316'
}
},
openTriggerId: 'open-chatbot-btn', // optional: use your own trigger element
position: {
mode: 'trigger' // opens the chat near the openTriggerId element
},
messageInputPosition: 'top', // optional: top input + bottom header + newest messages on top
title: 'Bsign Assistant',
imageUrl: 'https://cdn.shopify.com/s/files/1/0248/8198/7665/files/chatbot-logo.png?v=1750682293',
imageWidth: '120px',
// Modify the chat states depending on the user's URL
pageContext: {
'/pages/contact-us': {
timer: 1000,
exec: ({ open, messageOptions }) => {
messageOptions.setMessages(prev => [
...prev,
{content: contactUsMessage, sender: 'bot'}
])
open.setIsOpen(true);
}
}
},
themeTokens: {
promptBackground: 'rgba(15, 23, 42, 0.9)'
}
}, {
// default is true
isolateStyles: true
});
</script>
</body>mountChatbotWidget(..., ..., { isolateStyles: true }) is the default behavior.
In this mode, the widget is rendered inside a Shadow DOM root:
- global host-site CSS does not accidentally override widget styles;
- widget CSS does not leak and override unrelated site elements.
If you intentionally want regular DOM styling (for example, global overrides from your stylesheet), pass:
ChatbotWidget.mountChatbotWidget('#chatbot', props, {
isolateStyles: false
})When isolateStyles: false, include widget CSS manually:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ai-chatbot-widget@latest/dist/index.css" />If openTriggerId is provided, the widget listens for clicks on that element and opens the dialog.
When this prop is used, the built-in floating open button and notification badge are not rendered.
Use the optional position prop for flexible placement.
position?: {
mode?: 'preset' | 'coordinates' | 'trigger';
// preset mode
preset?:
| 'bottom-right'
| 'bottom-left'
| 'top-right'
| 'top-left'
| 'bottom-center'
| 'top-center'
| 'center-right'
| 'center-left'
| 'center';
// coordinates mode
x?: number | string; // e.g. 24 or '24px'
y?: number | string; // e.g. 120 or '120px'
// trigger mode (near openTriggerId element)
gap?: number; // distance from trigger to chat window, px
offsetX?: number; // additional horizontal offset, px
offsetY?: number; // additional vertical offset, px
}Preset area example:
position: {
mode: 'preset',
preset: 'top-left'
}Fixed coordinates example:
position: {
mode: 'coordinates',
x: 40,
y: 140
}Open near trigger example:
openTriggerId: 'open-chatbot-btn',
position: {
mode: 'trigger',
gap: 10,
offsetY: -20
}Use messageInputPosition to control where the input lives.
messageInputPosition?: 'bottom' | 'top''bottom'(default): header is on top, input is on bottom, newest messages appear at the bottom.'top': input is on top, header moves to bottom, newest messages appear at the top.
Available presets: futuristic, lighty, boring, o Canada.
You can pass theme as:
- a preset string:
theme: 'futuristic'- or a config object with preset + token overrides:
theme: {
preset: 'boring',
tokens: {
headerBackground: 'linear-gradient(90deg, #1f2937, #111827)',
botMessageBackground: '#111827',
botMessageTextColor: '#ffffff',
openButtonBackground: '#111827',
badgeBackground: '#22c55e'
}
}Additionally, themeTokens can override tokens on top of theme:
themeTokens: {
promptBackground: 'rgba(17, 24, 39, 0.92)',
promptTextColor: '#ffffff'
}The widget uses CSS variables internally (--ai-chatbot-*), so you can also apply intentional host-level overrides by setting these variables on the mount target.
One of the chatbot’s most important features is its ability to manipulate widget states based on the page context (and this functionality will only expand over time).
At the moment, you can only modify states based on the URL the user is visiting.
Example usage:
pageContext: {
'/pages/contact-us': {
timer: 1000, // after how many ms executed
exec: ({ open, messageOptions }) => {
// Adds messages to existing
messageOptions.setMessages(prev => [
...prev,
{ content: "Hello! Do you want to contact us?", sender: 'bot' }
]);
// Automatically expands the widget
open.setIsOpen(true);
}
}
}All modifiable states are:
{
open: {
isOpen: boolean, // whether the widget is open
setIsOpen: (v: boolean) => void // open / close the widget
},
messageOptions: {
// All existing messages
messages: {
content: string,
sender: "user" | "bot"
}[],
// Function for setting messages
setMessages: (messages: {
content: string,
sender: "user" | "bot"
}[]) => void,
},
// Input field
input: {
inputValue: string,
setInputValue: (value: string) => void,
},
// Tips for the user
promptsOptions: {
prompts: string[],
setPrompts: (prompts: string[]) => void
},
// Thing that unfortunately doesn't work
scrollToBottom: () => void
}