Web Widget

Web Widget

The Web Widget lets you embed a live chat window powered by your AI bot directly onto any website. Customize it to match your brand and deploy in minutes.

Installation

1. Go to Channels → Web Widget in the left menu.

2. Click Create Widget and give it a name.

3. Configure the widget settings (see Customization below).

4. Copy the embed code snippet provided.

5. Paste the snippet into your website’s HTML, just before the closing </body> tag.

6. Save and publish your site — the widget will appear immediately.

Embed Code

<!-- Clienta.ai Web Widget -->
<script>
  window.ClientaConfig = {
    botId: "YOUR_BOT_ID",
    widgetId: "YOUR_WIDGET_ID",
  };
</script>
<script
  src="https://api.clienta.ai/widget/YOUR_WIDGET_ID/loader.js"
  async
></script>

Replace YOUR_BOT_ID and YOUR_WIDGET_ID with the values shown in your dashboard.

Nota

The widget script loads asynchronously and will not block your page load.

Customization

Option	Description
Theme Color	Set the primary color to match your brand (hex code or color picker)
Welcome Message	The first message displayed when a user opens the widget
Position	Choose bottom-right or bottom-left placement on the screen
Avatar	Upload a custom avatar image for the bot

Additional options include:

• Widget Title — Name shown in the widget header
• Placeholder Text — Hint text inside the message input box
• Auto-Open Delay — Automatically open the widget after N seconds (optional)
• Hide on Mobile — Toggle widget visibility on mobile devices

How It Works

1. User opens the widget — The chat window slides open from the corner of the page.

2. Message sent to bot — The user’s message is sent to Clienta.ai over a secure WebSocket connection.

3. AI processes and responds — The bot retrieves relevant content from the knowledge base and generates a reply.

4. Human handoff if needed — If confidence is low or the user requests a human, the conversation is routed to an available agent via the Conversations inbox.

WebSocket Real-time

The widget uses a persistent WebSocket connection for real-time, low-latency messaging. Key behaviors:

• Auto-reconnect — The client automatically reconnects if the connection drops.
• Typing indicator — Shows a typing animation while the bot is generating a response.
• Message history — Conversation history is preserved within the same browser session.
• Cross-tab sync — If the user has multiple tabs open, the conversation state is synced.

Markdown Responses

v1.6.4

AI and agent messages are rendered as formatted markdown instead of plain text. Supported formatting includes:

• Bold, italic, strikethrough
• Links (open in new tab automatically)
• Inline code and fenced code blocks
• Ordered and unordered lists
• Headings, blockquotes, and tables

All markdown content is sanitized with a strict allowlist to prevent XSS attacks. No configuration is needed — markdown rendering is enabled by default for all AI and agent responses. User messages remain plain text.

Brand Avatar

v1.6.4

Display your brand logo or a custom avatar in the widget header and on the home screen. Set the avatarUrl in Settings → Channels → Web → Customizer or pass it as config.theme.avatarUrl in the embed code.

• Only https:// URLs are accepted
• If the URL is invalid or the image fails to load, the default sparkle icon is shown
• Recommended: a square image (e.g. 128 × 128 px) for best results

See Widget Customization — Avatar for details.

AI vs Human Labels

v1.6.4

Every non-user message displays a small author label identifying the sender:

Author type	Label shown
AI bot	”AI Assistant” (localized)
Human agent	Agent’s name (e.g. “Sarah”)

Labels are localized in all 15 supported languages and accessible to screen readers. This helps visitors clearly distinguish between AI-generated and human responses, supporting transparency best practices.

Greeting Language

v1.6.2

The widget greeting message supports three language modes, configured in Settings → Channels → Web → Customizer → Greeting Mode:

Mode	Behavior
Static	Displays the same greeting to every visitor regardless of language
Match Visitor	Shows a per-language greeting — configure a different greeting text for each of the 15 locales
Org-Main	Always shows the greeting in the organization’s main response language (set in AI Settings)

In Match Visitor mode, any locale without a configured greeting falls back to the static greeting text.

See Widget Customization — Greeting Mode for step-by-step configuration.

Language Selector

v1.6.2

The widget can display a globe icon in the header that lets visitors explicitly choose their preferred language. This feature is disabled by default and must be enabled per widget in Settings → Channels → Web → Customizer.

When enabled:

• A globe (🌐) icon appears in the widget header
• Visitors can choose from up to 15 supported locales
• Selecting a language locks all AI responses to that language for the session, overriding auto-detection
• The lock persists even if the visitor types in a different language

Nota

The language selector lock takes precedence over auto-detection but can be overridden by the Force this language setting in AI Settings. If Force is enabled, the org language always wins regardless of the visitor’s selection.

RTL (Right-to-Left) Support

v1.6.2

The widget and landing page fully support RTL layouts for Arabic and Hebrew. When a visitor uses an RTL locale:

• The entire layout mirrors (text alignment, navigation, UI elements)
• The <html dir="rtl"> attribute is set automatically
• Chat messages and the input box align correctly for RTL reading flow

No manual configuration is needed — RTL activates automatically based on the selected locale.

Channel Limits by Plan

Plan	Max Channels
Free	1
Starter	2
Growth	5
Plus	6
Pro	15
Scale	30
Enterprise	50

Consejo

Need the widget on multiple domains? Each domain requires its own widget configuration. Create one widget per domain to track analytics separately.