alby-chatbot
Help your shoppers discover, research, and buy with confidence, wherever they are on your website.
Prerequisites
Ensure alby is installed to unlock these elements and elevate your storefront. Learn more here.
Usage
The alby-chatbot
component can be embedded in your webpage with various attributes to customize its behavior.
Basic Example
<alby-chatbot
widget-id="widget-id"
</alby-chatbot>
Properties
Attribute | Description | Type | Default | Required |
---|---|---|---|---|
widget-id | The unique identifier for the widget, found on the Widget Embed page in the alby Dashboard. Required for correctly loading the designated widget instance. | string | undefined | Yes |
show-launcher-button | Controls whether the launcher button is visible. This setting will override the option configured in the Alby admin UI. | boolean | undefined | No |
product-id | The external product ID, matching the identifier provided in your product feed | string | undefined | No |
variant-id | The unique identifier for a specific product variant, matching the variant ID in your product feed . This helps the AI provide more accurate responses by referencing the exact variant a shopper is viewing—such as different sizes, colors, or configurations of a product. | string | undefined | No |
product-ids | Comma-separated list of external product IDs for multi-product contexts. | string | undefined | No |
category | The product category for contextual AI responses. | string | undefined | No |
test-mode | Enables internal testing of the widget. When enabled, conversations created will not appear in the inbox or impact reporting. This is not related to A/B testing. | boolean | undefined | No |
aria-label | Accessibility label for the launcher button. | string | "Chat with our AI assistant" | No |
chat-window-label | Accessibility label for the chat window. | string | "AI Shopping Assistant" | No |
API
The alby-chatbot
component provides a comprehensive API for programmatically controlling the chatbot interface.
Methods
Method | Parameters | Description |
---|---|---|
show(focusInput?: boolean) | focusInput - Optional boolean to focus input | Opens the chat window |
hide() | None | Closes the chat window |
submitText(text: string) | text - String message | Shows chat and submits text |
Usage Examples
Basic Control
const chatbot = document.querySelector('alby-chatbot');
// Open chat
await chatbot.show();
// Close chat
await chatbot.hide();
// Submit text programmatically
await chatbot.submitText("Hello, I need help with my order");
Example
<button onclick="openChat()">Open Chat</button>
<button onclick="submitQuestion()">Ask Question</button>
<script>
const chatbot = document.querySelector('alby-chatbot');
async function openChat() {
await chatbot.show();
}
async function submitQuestion() {
await chatbot.submitText("What's my order status?");
}
</script>
CSS Variables Configuration
The alby-chatbot
component can be customized using CSS custom properties (CSS variables). These variables allow you to control the appearance and behavior of the chatbot without modifying the component's internal styles.
Usage
You can set these variables using inline styles on the component:
<alby-chatbot
style="--alby-launcher-button-color: #007bff; --alby-chat-border-radius: 20px"
></alby-chatbot>
Priority Order
CSS variables follow this priority order (highest to lowest):
- Inline styles - Set directly on the component element
- Widget styling - Configured through the Alby dashboard
- Default values - Built-in component defaults
Available CSS Variables
CSS Variable | Description | Default Value |
---|---|---|
--alby-launcher-button-color | Sets launcher button background color | #1F2A37 |
--alby-launcher-button-icon-color | Sets launcher button icon color | #ffffff |
--alby-chat-border-radius | Sets the border radius of chat window | 16px |
--alby-chat-header-icon-display | Sets display property of header icon | flex |
--alby-chat-header-icon-size | Sets the size of header icon | 16px |
--alby-chat-header-icon-color | Sets the color of header icon | #1F2A37 |
--alby-disclaimer-text-color | Sets the disclaimer text color | #9095a0 |
--alby-chat-button-radius | Sets the border radius of chat buttons | 9999px |
--alby-chat-button-padding | Sets the padding of chat buttons | 8px 16px |
--alby-chat-button-icon-display | Sets display property of button icons | block |
--alby-chat-button-icon-size | Sets the size of button icons | 16px |
--alby-chat-button-icon-color | Sets the color of button icons | #9CA3AF |
--alby-chat-button-hover-icon-color | Sets button icon color on hover | #9CA3AF |
--alby-chat-button-background-color | Sets button background color | #F0F2F7 |
--alby-chat-button-hover-background-color | Sets button background color on hover | #F0F2F7 |
--alby-chat-button-text-color | Sets button text color | #1F2A37 |
--alby-chat-button-hover-text-color | Sets button text color on hover | #1F2A37 |
--alby-chat-button-border-color | Sets button border color | #E0E3EB |
--alby-chat-button-border-width | Sets button border width | 0px |
--alby-chat-button-border-radius | Sets button border radius | 9999px |
--alby-chat-input-background-color | Sets input background color | #F9FAFB |
--alby-chat-input-text-color | Sets input text color | #1F2A37 |
--alby-chat-input-border-color | Sets input border color | #E1E1E1 |
--alby-chat-input-border-width | Sets input border width | 1px |
--alby-chat-input-border-radius | Sets input border radius | 12px |
--alby-chat-input-placeholder-color | Sets input placeholder color | #9CA3AF |
--alby-chat-input-padding | Sets input padding | 8px 4px 8px 16px |
--alby-chat-input-focus-border-color | Sets input border color when focused | #E1E1E1 |
--alby-chat-input-focus-border-width | Sets input border width when focused | 1px |
--alby-chat-input-focus-background-color | Sets input background color when focused | #ABB3C4 |
--alby-chat-input-focus-text-color | Sets input text color when focused | #1F2A37 |
--alby-chat-user-message-background-color | Sets user message background color | #1F2A37 |
--alby-chat-user-message-text-color | Sets user message text color | #ffffff |
--alby-chat-user-message-border-radius | Sets user message border radius | 9999px |
--alby-chat-user-message-border-color | Sets user message border color | #ffffff |
--alby-chat-user-message-border-width | Sets user message border width | 0px |
--alby-chat-user-message-padding | Sets user message padding | 8px 16px |
--alby-chat-ai-message-background-color | Sets AI message background color | #ffffff |
--alby-chat-ai-message-text-color | Sets AI message text color | #1F2A37 |
--alby-chat-ai-message-border-radius | Sets AI message border radius | 0px |
--alby-chat-ai-message-border-color | Sets AI message border color | #ffffff |
--alby-chat-ai-message-border-width | Sets AI message border width | 0px |
--alby-chat-ai-message-padding | Sets AI message padding | 0px |
Updated 21 days ago