The Alysium Widget: Make AI Feel Native on Your Site

TL;DR: The Alysium widget is a 60×60px floating button that expands to a 400×600px chat window on desktop and full-screen on mobile. Configure it in four sections — Theme & Appearance, Chat Window, Features, and Agent Menu — then embed via a single script tag. Future configuration changes apply to existing embeds automatically; no re-copying needed.

The Alysium widget is what your visitors actually interact with on your website. Getting it right means configuring it to look like it belongs on your site and behave the way your visitors expect.

Here's every configuration option and the embedding process, end to end.

Understanding the Widget Structure

The widget is a circular floating button (60×60px) in the bottom-right corner by default — repositionable to any corner. When closed, it shows a message icon with an optional unread message badge. When expanded: 400×600px on desktop, full-screen on mobile.

First-time visitors land on a welcome screen: agent name, avatar, welcome message, and up to five conversation starters as clickable buttons. Once a conversation starts, the chat interface replaces the welcome screen. Returning visitors go straight to their conversation history — this is always on and can't be disabled.

Section 1: Theme & Appearance

Choose from 36 themes in a grid; the live preview panel updates immediately. If none match your brand precisely, override the accent color with any hex value. For complete control, use the custom CSS field.

The 36 themes cover every brand context from formal (Corporate, Business) to warm (Pastel, Garden) to premium (Luxury, Silk, Abyss) to technical (Dark, Wireframe). Most creators find what they need without CSS.

Tip: Test the widget against your actual website homepage, not just the preview. The widget should feel like it belongs on your page, not like it was added from outside.

Section 2: Chat Window

Widget header title: What appears at the top of the open chat window. Doesn't have to be your agent's name — "Ask About Our Menu" or "Student Support" sets clearer expectations than a generic agent name.

Input placeholder text: The greyed-out text in the chat input before visitors start typing. "Type a message..." is the forgettable default. "Ask about our services..." or "What can I help you find?" is more useful.

Agent avatar toggle: Show or hide the agent avatar next to its messages. On by default; some creators prefer the cleaner look without it.

Section 3: Features

Starter prompts toggle: Show or hide the conversation starters on the welcome screen. If you haven't configured starters yet, turn this off rather than showing an empty prompt area.

File upload toggle: Allow visitors to attach files to messages — up to 20 files per conversation, 30MB per file. Useful for agents where visitors need to share context (writing feedback, coaching intake, tax questions). Turn it off if your agent doesn't benefit from visitor uploads.

Conversation history: Always on for returning visitors. Shown as informational copy — not a toggle. It cannot be disabled.

Section 4: Agent Menu

The agent menu appears via a small icon inside the open chat window. Four optional slots, each configured independently:

Terms & Privacy: Paste a URL to your terms of service or privacy policy. Displays as a menu link.

Help & Support: Either a URL redirect or an inline contact card — support message, email, and optionally phone, website, Discord link, Twitter, physical address, and free-form info.

About Profile: Your creator card — name, story, bio, credentials (multiple), and optional links: LinkedIn, Twitter, website, booking link, space name, space description, value bullets, "Learn more" link. Underused feature that converts an anonymous chatbot into a credentialed expert AI.

Contact Info: Same fields as Help & Support, as a standalone contact card.

None are required. Configure whichever are relevant.

Embedding the Widget

Click Publish in the agent builder. Alysium generates a script tag. Copy it.

Squarespace: Settings → Advanced → Code Injection → Footer. Paste and save.

Wix: Site & App → Custom Code → Add Code → Body - end, all pages. Paste and save.

WordPress: Use a theme with code injection or install "Insert Headers and Footers." Paste in the footer section.

Any HTML site: Paste just before the closing </body> tag.

Once embedded, future configuration changes — themes, toggles, header text, agent menu items — apply automatically. You only need to re-copy the script tag if you're moving to a new domain or changing domain restriction settings.

Domain Restriction

By default, your script tag loads on any website. To restrict it to your own site: go to Deployment settings, add your approved domains. The widget refuses to load anywhere not on the list.

Widget Across Different Site Builders

The script tag Alysium generates is standard HTML and works anywhere you can paste raw HTML. On Squarespace, use a Code Block in any section. On Wix, use an HTML iframe component — paste the script inside it. On WordPress, a Custom HTML block in the block editor works cleanly. On any custom HTML site, paste the script tag before the closing </body> tag.

If your site builder wraps pasted HTML in an iframe, the widget may not behave correctly — floating button positioning can be affected by iframe boundaries. In those cases, contact your site builder's support to confirm their method for injecting raw scripts at the page level.

Configure yours now. Open your agent builder — Widget Appearance is in the left navigation.

Testing Before You Publish

Before you hit Publish, run through three test conversations yourself. Ask the most common question your visitors will ask. Ask something the agent shouldn't know. Ask something that would normally trigger an escalation. Confirm the agent responds the way your instructions specify, not just adequately.

The live preview panel shows the widget appearance, not the conversation quality. Testing the actual conversation in the Preview mode before publishing is how you catch instruction gaps before real visitors find them.

The Mobile Experience

On mobile, the widget opens full-screen — no 400×600px window. The chat takes over the entire viewport. This is by design: small chat windows on small screens produce a poor experience. On mobile, visitors get the same conversation quality but with a full-screen layout that's easier to read and type in.

If your audience is majority mobile (common for small business websites, especially restaurant and hospitality pages), test the widget on an actual mobile device before publishing. The theme and header title that look good on desktop sometimes render differently on a smaller screen.

The Unread Message Badge

When the widget is minimized and new messages arrive — whether from a returning conversation or a proactive first message in future functionality — an unread badge appears on the floating button showing the count (or "9+" for large numbers). The badge pulses to draw attention.

This is a passive engagement mechanism. Visitors who opened the widget, started a conversation, minimized it, and navigated elsewhere see the badge when they return. It's a low-friction prompt to come back to the conversation rather than having to find the widget again.

What Happens When a Visitor Returns

Returning visitors — anyone who has had a conversation with your agent before — go directly to their conversation history when they open the widget. The welcome screen (with conversation starters) only appears to first-time visitors or visitors who have cleared their browser data.

This is always on and cannot be disabled. The practical implication: a visitor who asked about your pricing last week picks up where they left off. They don't have to re-explain their situation. The conversation context carries forward.

For agents deployed in coaching or advisory contexts, this is significant. The agent remembers the conversation. The client can reference earlier exchanges. It functions more like an ongoing conversation partner than a one-time query tool.

Common Configuration Mistakes

Forgetting the input placeholder text. The default placeholder adds no value. Replacing it with something specific about your agent's purpose takes two minutes and improves first-impression engagement.

Skipping the About Profile. For coaches and consultants, the About Profile is the most high-value configuration in the Agent Menu. It's two minutes to fill in. Most creators never open it.

Not testing on mobile. If you build on desktop and only test on desktop, you miss how the full-screen mobile experience feels. Check it.

Setting domain restriction and forgetting. If you configure domain restriction, make sure you've added every domain where you want the widget to load — including staging and preview environments if relevant. A broken widget on your staging site because the domain isn't whitelisted is a minor inconvenience. A broken widget on your live site because you forgot to add a subdomain is more significant.

Widget Troubleshooting

Most widget issues come down to one of four things:

The widget doesn't appear at all. Check that you published the agent — an unpublished agent produces a valid script tag that silently loads nothing. The Publish button is in the Deploy tab; make sure the status shows as Published, not Draft.

The widget appears but doesn't answer questions. This usually means the knowledge base is still indexing. After uploading documents, Alysium processes them in the background — status indicators in the knowledge base panel show when each file finishes. If documents are all green and the agent still won't answer, check whether your instructions include a phrase like "only answer questions about X" that might be filtering out the user's question.

The widget loads but looks wrong on mobile. The widget goes full-screen on mobile automatically. If that's disruptive to your site's mobile experience, note the behavior in your agent's About description so visitors know what to expect. There's no way to keep the compact layout on mobile — it's full-screen by default.

The domain restriction is blocking embed. If you configured domain restrictions and the widget isn't loading, open browser developer tools and check the console for CORS-related errors. Make sure the domain you're embedding on exactly matches what you entered — including whether the domain starts with www. — and that you haven't accidentally added a trailing slash.

A Note on the Live Preview

The Widget Appearance builder includes a live preview panel that reflects every change in real time. This is the fastest way to get your theme, header text, and avatar right before touching your live site. Spend time with the preview — the 36 themes can look very different from their names, and what reads as "Corporate" in a dark mode context reads completely differently against your light-background site.

Widget Across Different Site Builders

The script tag Alysium generates is standard HTML and works anywhere you can paste raw HTML. On Squarespace, use a Code Block in any section. On Wix, use an HTML iframe component — paste the script inside it. On WordPress, a Custom HTML block in the block editor works cleanly. On any custom HTML site, paste the script tag before the closing </body> tag.

If your site builder wraps pasted HTML in an iframe, the widget may not behave correctly — floating button positioning can be affected by iframe boundaries. In those cases, contact your site builder's support to confirm their method for injecting raw scripts at the page level.

Configure yours now. Open your agent builder — Widget Appearance is in the left navigation.