Documentation
Embedding the widget
One script tag before the closing body element. No dependencies, nothing fetched from other companies' servers, no changes to your code.
The snippet
Your organisation key is in the panel. It is public by design and lives in your page's source.
<script src="https://aivatary.com/assets/caip-widget.js"
data-tenant-key="pw_0123456789abcdef"
data-api-base="https://app.aivatary.com"
defer></script>Why the key can be public
The organisation key is not a secret. The widget exchanges it for a short lived session token, and access is further limited by the allowed domain list. No secret ever reaches the browser, so copying the snippet onto someone else's page achieves nothing.
Optional attributes
| Attribute | Default | Meaning |
|---|---|---|
| data-tenant-key | required | Your organisation's public key |
| data-api-base | required | The address the platform runs at |
| data-theme-attr | data-theme | Name of the attribute on the html element the theme is read from |
| data-locale | page language, then pl | Session language: pl or en |
| data-auto-open | desktop | Automatic panel opening: desktop for windows from 900 pixels, always, never |
| data-avatar-selector | [data-caip-avatar] | Selector of the container the avatar should occupy in hero mode |
Theme
- How it is read
- The widget looks at the attribute named by data-theme-attr on the html element. The value light means the light theme; any other value or none means dark.
- No reload needed
- A theme switch on your page takes effect immediately, because the widget watches the attribute for changes.
- System preference
- The widget deliberately ignores the operating system's light and dark setting, exactly as this site does. Your attribute decides, so the widget never diverges from the rest of the page.
The allowed domain list
- Where you set it
- In the organisation settings, one entry per domain the widget should answer on.
- What happens off the list
- A request from a domain not on the list is not served. That is exactly why the public key does not have to be a secret.
- Test environment
- A test domain has to be added separately. A local address is a domain too.
The widget does not appear
Is the domain on the allowed list?
The most common cause. Check that the exact domain you open the page from is entered, including any www prefix.
Did the script load?
The network tab of your browser tools should show the widget file. Blocking by an ad blocking extension is the second most common cause.
Is the key correct?
The key starts with the pw_ prefix and comes from your organisation's panel. A key from another environment will not work.
Is the page loading the widget twice?
The widget guards against double loading, but two different keys on one page is a configuration conflict, not a case to handle.
Is something covering the widget?
An element with a very high stacking value can hide it. The widget draws in its own tree, so this cannot be fixed with your CSS; the covering element's layer has to come down.
Next: the avatar inside your page
If you want the conversation to start where the character stands rather than in a corner bubble, move on to hero mode.