Floating avatar

The floating avatar is the round button that opens your popup widget (render: 'bottom-right' or 'bottom-left'). You can change how it behaves without touching the widget’s HTML. Its look, the chat window, and the chat history stay exactly as they are. Every option below is off by default. With nothing set, the avatar sits where it always has.

Options

Option	What it does
`draggable`	Visitors can drag the avatar. When they let go it snaps to the nearest side, and it stays there on their device on every page. The chat window still opens in its usual corner.
`greetingAutoHideSeconds`	The greeting bubble minimises itself after this many seconds and the avatar stays. It stays minimised for the rest of the visit.
`hideGreetingOnMobile`	Only the avatar shows on screens narrower than 768px.
`mobileSize`	Avatar size in px on mobile (36 to 96, default 64).
`mobileOffsetX`	Distance from the side edge in px on mobile (default 45).
`mobileOffsetY`	Distance from the bottom edge in px on mobile (default 45).
`avoidSelectors`	CSS selectors of things the avatar must never cover, such as a sticky Add to cart bar. While one of them is on screen under the avatar, the avatar moves up above it, and moves back when it goes away.

Set them in the dashboard

Open your agent, go to Settings → User Interface → Floating avatar, and save. This applies everywhere the agent is installed.

Or set them in your embed code

Add a launcher object to VG_CONFIG. Anything you set here overrides the dashboard for that site only.

<script defer>
  (function() {
    window.VG_CONFIG = {
      ID: "YOUR_AGENT_ID",
      region: 'na',
      render: 'bottom-right',
      stylesheets: ["https://vg-bunny-cdn.b-cdn.net/vg_live_build/styles.css"],
      launcher: {
        draggable: true,
        greetingAutoHideSeconds: 8,
        hideGreetingOnMobile: true,
        mobileSize: 52,
        mobileOffsetX: 16,
        avoidSelectors: [
          ".product-form__buttons",   // your theme's Add to cart area
          ".sticky-atc"               // a sticky Add to cart bar, if your theme has one
        ]
      }
    };
    var VG_SCRIPT = document.createElement("script");
    VG_SCRIPT.src = "https://vg-bunny-cdn.b-cdn.net/vg_live_build/vg_bundle.js";
    VG_SCRIPT.defer = true;
    document.body.appendChild(VG_SCRIPT);
  })();
</script>

On Shopify, find the selector of your Add to cart bar by right-clicking it in your browser and choosing Inspect. Use a class or id from that element, for example .product-form__buttons.

JavaScript API

Once the widget has loaded, window.VG_ADMIN.launcher gives you full control from your own scripts.

const launcher = window.VG_ADMIN.launcher;

launcher.setPosition({ side: "left", bottom: 120 }); // for this page view; a visitor's own drag still wins
launcher.resetPosition();     // back to the default corner, forgets the visitor's drag
launcher.hideGreeting();      // minimise the greeting now
launcher.showGreeting();
launcher.hide();              // hide the avatar entirely, e.g. while your cart drawer is open
launcher.show();
launcher.setAvoidSelectors([".sticky-atc"]);
launcher.getState();          // { side, bottom, lift, hidden, greetingVisible, draggable, movedByVisitor }

Hiding the avatar while a drawer or quick-view is open:

document.addEventListener("cart:open", () => window.VG_ADMIN?.launcher?.hide());
document.addEventListener("cart:close", () => window.VG_ADMIN?.launcher?.show());

Events

The widget reports launcher changes on the same VG_Events event as chat_open and chat_close.

document.addEventListener("VG_Events", (e) => {
  const { event, data } = e.detail;
  if (event === "launcher_moved") console.log("avatar moved", data);        // { side, bottom, byVisitor }
  if (event === "launcher_greeting_minimised") console.log(data.reason);    // "timer" or "api"
});

Styling with CSS

These class names are stable and safe to target from your own stylesheet:

Class	Element
`.vg-widget-controls-container`	The avatar’s wrapper (has `data-vg-side="left"` or `"right"`)
`.vg-open-btn` / `.vg-open-btn--img`	The avatar button and its image
`.vg-proactive-message--container`	The greeting bubble
`.vg-proactive-btn--close`	The greeting’s close button
`.vg-proactive-notification--container`	The unread messages badge

Prefer the options above over CSS for position and size. CSS that moves the avatar with !important will stop dragging and lifting from working.

Get Started

Build Your Agent

Voice

Deploy

Channels & Integrations

Features

Business

Support

Options

Set them in the dashboard

Or set them in your embed code

JavaScript API

Events

Styling with CSS

​Options

​Set them in the dashboard

​Or set them in your embed code

​JavaScript API

​Events

​Styling with CSS

Options

Set them in the dashboard

Or set them in your embed code

JavaScript API

Events

Styling with CSS