Web Widget Configuration

In this section, you’ll learn how to integrate and customize Lovi’s web widget to perfectly match the design and functionality of your website

This is the bridge between your clever Agent and your website visitors.

The Web Widget is that friendly little bubble in the corner of the screen that says “Hello!”. Integrating it is a doddle: you just add a snippet of code to your site, and voilà! Your AI Agent is ready to chat 24/7 without you lifting a finger.

🎛️ Overview of Your Widgets

This is your widget command centre. Here you can see every chat bubble you’ve created.

• Why have more than one? You might want a “Sales Bot” for your pricing page and a “Tech Support” bot for your help centre. Here you manage them all.
• Key Actions per Widget:
  • 📋 Copy Script: Grab the magic code to paste onto your website.
  • ⚙️ Configure: The fun part. Tweak colours, messages, and behaviour (we’ll get to this in a mo).
  • 🗑️ Delete: Bin it if you don’t need it.

---

How to embed (chat)

Paste this before </body>. Do not set mode="voice" (that loads the voice widget).

<script
  customer="YOUR_ACCESS_KEY"
  widget="YOUR_WIDGET_ID"
  src="https://widget.lovi.ai/iawidget.js"
  defer
></script>

Do not use language="en". The loader reads language-lovi. If you omit it, it uses navigator.language (first two letters; un → en).

Attribute	Required	What it is
src	Yes	https://widget.lovi.ai/iawidget.js
customer	Yes	Company access key (not a loose “company ID”). Same value the script sends as access_key.
widget	Yes	Widget UUID.
language-lovi	No	Forced language (es, en, …).
showClose	No	Default true. showClose="false" opens chat full page and hides close.
dom	No	HTML element id (getElementById), not a CSS selector (#foo / .bar). Embed runs if dom is set, or if config is_fullscreen is on and element_dom exists. If there is no node, there is no embed.
extra-context	No	Comma-separated list → context_extra on the message.
lovi-source	No	Stored in info_user.source.
whatsapp_type / whatsapp_number	No	See WhatsApp below.
mode	No	Omit it (or anything other than voice) for text chat.

Loader order: mode="voice" → WhatsApp full → chat.

The url attribute on <script> does nothing. Config is cached 24 hours in localStorage under the widget id.

URLs

• Loader: https://widget.lovi.ai/iawidget.js
• Chat iframe: https://widget.lovi.ai (optional ?showClose=false and/or lang={language-lovi})
• Config: GET https://cloud.lovi.ai/functions/v1/widget?access_key=…&id_widget=…&language=… (the script adds the key; do not put it in screenshots)
• Messages inside the iframe: …/functions/v1/widget/{user,chat,messages,…} — session internals, not a public embed API

Do not use voice-widget or ?mode=voice on this page.

The loader creates #app-chatbot on the host. Chat runs in iframe #app-chatbot-iframe (allow="fullscreen; autoplay; encrypted-media; picture-in-picture" — no microphone). Handshake is postMessage (get_widget, get_customer, data_collection, save_customer, close, reset, new_message).

Desktop window: 450px × 85vh (max 824px), bottom/right: 10px (or left if floating_position is "left"). Viewport max-width 650px (and max-height 650px): iframe is already 100% of the viewport (border-radius: 0). That is not the config “Full screen” toggle. Config is_fullscreen + element_dom embeds in a node; showClose="false" covers the whole page on any viewport. Launcher: bottom: 10px; right: 20px.

WhatsApp (two paths)

1. Script: whatsapp_type="full" and a non-empty whatsapp_number → chat does not load; only a button to https://wa.me/{number}.
2. Widget config: whatsapp_type == true and a number, only if innerWidth ≤ 650 → replaces the chat bubble on mobile.

If the HTML also has mode="voice", voice wins over WhatsApp full.

Host allowlist (CSP / firewall)

widget.lovi.ai and cloud.lovi.ai. The widget does not send a Content-Security-Policy header.

---

🎨 Customising Your Widget (The Art Class)

Click on the gear icon ⚙️ to enter the configuration lab. Let’s make this widget truly yours.

1. The Basics

• AI Agent: Which brain is powering this chat? Select one of your agents from the list.
• Languages: Does your site speak English, Spanish, and French? Tell the widget so it doesn’t look silly.

2. Floating Message (The Hook 🪝)

Don’t let your bot hide! Set a catchy message that pops up above the icon.

• Boring: “Chat here.”
• Better: “Hi there! Need help with your order? 👋”

⚠️ Heads up: Add translations for all your languages. You don’t want Spanish visitors seeing a blank bubble!

3. Look & Feel (Dress to Impress)

• Header: Choose what shows at the top. Just a title? Your logo? An avatar of a robot wearing a monocle? It’s up to you.
• Colours: Use the eyedropper tool 🖊️ to match your brand exactly.
  • Main Colour: The message bubbles and send button.
  • Text Colour: Make sure it’s readable! Yellow text on a white background is a crime against eyesight.

4. The Gatekeeper: Data Collection Forms 📝

Do you want to know who you’re talking to before they start chatting? Enable the Form.

• Ask for Name, Email, or Phone.
• Make fields “Required” if you’re strict, or “Optional” if you’re chill.
• GDPR / Privacy: Add a link to your policy so you stay legal. 👮‍♂️

5. Smart Data Collection (Advanced 🤓)

For each key in the widget config, the loader reads localStorage or sessionStorage or a JS cookie, or (if source === "js_global") a window variable by dotted path. It always sends url: location.href. The output name is optional. Those values are injected into message context; the widget does not automatically greet “Hello, John” unless your agent prompt does.

---

🛠️ Extra Tweaks & Layout

Fine-tune the experience:

• Position: Left or Right? (Right is standard, Left is for rebels).
• Full Screen (config): Together with element_dom, this embeds the chat in a page node. It is not “mobile full bleed” — at max-width: 650px the iframe is already full viewport.
• Embed (dom): HTML element id of a node on the page (not #id / .class). If the node is missing, there is no embed.
• Custom CSS: Injected as a <style> tag in the iframe and on the host (#app-chatbot) without encapsulation, so host rules can affect the page. Iframe selectors: .widget_chat, .widget_chat_window, … Host launcher: .widget_chat_switch, .widget_chat_switch_open, #app-chatbot-iframe.

---

🎨 Custom CSS — The Designer’s Guide

Are the preset colours and options too limiting? The Custom CSS field gives you full control over the widget’s look. Here you can write CSS rules that tweak styles, override default classes, or even add animations.

Where to find it: Open the widget configuration (⚙️ icon), expand the “Custom CSS” section, and type your code in the text area.

⚙️ How it works under the hood

What you write here isn’t magic — it’s quite predictable once you get it:

1. Your CSS is saved alongside the widget configuration.
2. When the widget loads, your CSS is injected twice: a <style> tag inside the chat iframe (scoped to the chat) and a <style> tag on the host (#app-chatbot) with no encapsulation (it can affect the rest of the page).
3. Iframe rules load after default iframe styles, so they usually win ties there. Host selectors (.widget_chat_switch, #app-chatbot-iframe) style the launcher on your page.

🎯 Scope: Chat-window classes (.widget_chat, .widget_chat_window, …) apply inside the iframe. Launcher rules on the host are not isolated from your site CSS.

💪 My rule isn’t applying? Because our base styles are specific, sometimes your rule “ties” and doesn’t win. If a change has no effect, add !important to the end of the property (e.g. border-radius: 0 !important;) or use a more specific selector.

🧩 Selectors you can use

These are the real “tags” of the widget’s parts. Target them with your CSS:

Selector	What it is
.widget_chat	The root container of the whole widget
.widget_chat_window	The chat window when it’s open
.widget_chat_window_header	The top header (avatar, title, buttons)
.widget_chat_window_body	The area where messages appear
.widget_row_message	Each message row (use .widget_row_message_end for the user’s)
.widget_message_bot	The Agent’s message bubbles
.widget_message_content	The text inside each bubble
.widget_message_botones / .widget_message_boton	The quick-reply buttons
.widget_chat_window_footer	The bottom bar where you type
#inputMessage	The text field for typing the message
.widget_form_submit	The send button
.widget_chat_formulario	The data-collection form (name, email, etc.)
.widget_chat_formulario_body_input_asterisk	The red asterisk on required fields
.widget_chat_window_footer_legends	The “Generated by lovi.ai” signature in the footer

💡 Practical examples

Squarer bot bubbles with a shadow:

.widget_message_bot {
  border-radius: 6px !important;
  box-shadow: 0 2px 8px rgba(0,0,0,0.12);
}

Make the message text bigger:

.widget_message_content {
  font-size: 16px !important;
  line-height: 1.5;
}

Header with a brand gradient:

.widget_chat_window_header {
  background: linear-gradient(90deg, #6a11cb, #2575fc) !important;
}

Give the typing area more breathing room:

.widget_chat_window_footer {
  padding: 14px !important;
}

🧪 Always test it in the Playground (see below) before publishing. A forgotten } can break several styles at once.

---

🧪 Test Drive (Playground)

Before you paste the code on your live site, give it a whirl in the Playground.

• Does the colour clash?
• Is the Agent being polite?
• Does the form work?

Once you’re happy, copy that script and go live! 🚀

If you want a spoken call in the browser (microphone, not a chat bubble), use the voice widget.