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

AttributeDescriptionTypeDefaultRequired
widget-idThe unique identifier for the widget, found on the Widget Embed page in the alby Dashboard. Required for correctly loading the designated widget instance.stringundefinedYes
show-launcher-buttonControls whether the launcher button is visible. This setting will override the option configured in the Alby admin UI.booleanundefinedNo
product-idThe external product ID, matching the identifier provided in your product feedstringundefinedNo
variant-idThe 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.stringundefinedNo
product-idsComma-separated list of external product IDs for multi-product contexts.stringundefinedNo
categoryThe product category for contextual AI responses.stringundefinedNo
test-modeEnables 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.booleanundefinedNo
aria-labelAccessibility label for the launcher button.string"Chat with our AI assistant"No
chat-window-labelAccessibility 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

MethodParametersDescription
show(focusInput?: boolean)focusInput - Optional boolean to focus inputOpens the chat window
hide()NoneCloses the chat window
submitText(text: string)text - String messageShows 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):

  1. Inline styles - Set directly on the component element
  2. Widget styling - Configured through the Alby dashboard
  3. Default values - Built-in component defaults

Available CSS Variables

CSS VariableDescriptionDefault Value
--alby-launcher-button-colorSets launcher button background color#1F2A37
--alby-launcher-button-icon-colorSets launcher button icon color#ffffff
--alby-chat-border-radiusSets the border radius of chat window16px
--alby-chat-header-icon-displaySets display property of header iconflex
--alby-chat-header-icon-sizeSets the size of header icon16px
--alby-chat-header-icon-colorSets the color of header icon#1F2A37
--alby-disclaimer-text-colorSets the disclaimer text color#9095a0
--alby-chat-button-radiusSets the border radius of chat buttons9999px
--alby-chat-button-paddingSets the padding of chat buttons8px 16px
--alby-chat-button-icon-displaySets display property of button iconsblock
--alby-chat-button-icon-sizeSets the size of button icons16px
--alby-chat-button-icon-colorSets the color of button icons#9CA3AF
--alby-chat-button-hover-icon-colorSets button icon color on hover#9CA3AF
--alby-chat-button-background-colorSets button background color#F0F2F7
--alby-chat-button-hover-background-colorSets button background color on hover#F0F2F7
--alby-chat-button-text-colorSets button text color#1F2A37
--alby-chat-button-hover-text-colorSets button text color on hover#1F2A37
--alby-chat-button-border-colorSets button border color#E0E3EB
--alby-chat-button-border-widthSets button border width0px
--alby-chat-button-border-radiusSets button border radius9999px
--alby-chat-input-background-colorSets input background color#F9FAFB
--alby-chat-input-text-colorSets input text color#1F2A37
--alby-chat-input-border-colorSets input border color#E1E1E1
--alby-chat-input-border-widthSets input border width1px
--alby-chat-input-border-radiusSets input border radius12px
--alby-chat-input-placeholder-colorSets input placeholder color#9CA3AF
--alby-chat-input-paddingSets input padding8px 4px 8px 16px
--alby-chat-input-focus-border-colorSets input border color when focused#E1E1E1
--alby-chat-input-focus-border-widthSets input border width when focused1px
--alby-chat-input-focus-background-colorSets input background color when focused#ABB3C4
--alby-chat-input-focus-text-colorSets input text color when focused#1F2A37
--alby-chat-user-message-background-colorSets user message background color#1F2A37
--alby-chat-user-message-text-colorSets user message text color#ffffff
--alby-chat-user-message-border-radiusSets user message border radius9999px
--alby-chat-user-message-border-colorSets user message border color#ffffff
--alby-chat-user-message-border-widthSets user message border width0px
--alby-chat-user-message-paddingSets user message padding8px 16px
--alby-chat-ai-message-background-colorSets AI message background color#ffffff
--alby-chat-ai-message-text-colorSets AI message text color#1F2A37
--alby-chat-ai-message-border-radiusSets AI message border radius0px
--alby-chat-ai-message-border-colorSets AI message border color#ffffff
--alby-chat-ai-message-border-widthSets AI message border width0px
--alby-chat-ai-message-paddingSets AI message padding0px