> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Floating avatar

> Let visitors drag the chat avatar, minimise the greeting automatically, and keep the avatar off your buttons on mobile.

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.

```html theme={null}
<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>
```

> [!TIP]
>
> 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.

```javascript theme={null}
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:

```javascript theme={null}
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`.

```javascript theme={null}
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 |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.