Documentation
Hero mode: the avatar inside your page
You point at a container in your layout and the widget puts the character and a control bar inside it. The conversation starts where the visitor is already looking.
Markup on your page
You drive the conversation with your own attributes, without touching the widget's programming interface.
<!-- The container the avatar will occupy. Its contents are the fallback. -->
<div class="hero-avatar" data-caip-avatar>
<picture><img src="/images/ada.png?v=2" alt="Ada, AI assistant"></picture>
</div>
<!-- Visible disclosure next to the character. The widget adds its own
note, but only while it holds the container. -->
<p>Ada is an AI assistant. You are talking to a system, not a person.</p>
<!-- Your voice call button, anywhere on the page -->
<button type="button" data-caip-call>Talk to Ada</button>
<!-- Your button to open the text chat -->
<button type="button" data-caip-open>Write to us</button>Three attributes
| Attribute | Meaning |
|---|---|
| data-caip-avatar | The container the widget takes over. It receives its own closed style tree holding the avatar frame and a control bar |
| data-caip-call | Starts a voice conversation in the avatar. Does not open the bubble |
| data-caip-open | Opens the text chat panel |
The rules people ask about most
- The fallback disappears late
- The image in the container stays until the frame comes up correctly. A bad configuration leaves the page with your image, not with an empty rectangle.
- The session opens lazily
- The first click opens the session and then the voice conversation. The click stays a visitor gesture, which is what makes the microphone and audio playback permitted by the browser.
- There is only one conversation
- There is one frame at a time and, with the chat panel open, it belongs to the panel: your container returns to its fallback for that time and takes the frame back when the panel closes. The exception is a conversation already running in the avatar, which keeps its frame while the panel shows the call controls alone.
- Do not place a button right below the container
- After the container is taken over, the widget's bar draws its own start button there. Your button placed directly beneath would sit on top of it.
- Height
- The frame takes its width from the container and its height from a square ratio. A container with automatic height needs nothing set. A container with an explicit height wins, and the growing conversation bar takes height from it rather than from the page, so the layout does not jump.
- When voice is off
- Call buttons in the avatar hide permanently, and your own button does not go dead: it opens the chat instead.
- Put the disclosure in your fallback
- While the panel holds the frame, the character in your page is your own fallback, without the widget's bar and therefore without its note. Give that fallback a visible line saying the character is an AI assistant, not only an alt text or an aria-label.
Content security policy
The avatar is embedded in a frame. If your page sends a Content-Security-Policy header, it has to allow a frame from app.aivatary.com in the frame-src directive. On our side, embedding is limited by frame-ancestors to the domains on your allowed list, so the frame cannot be placed on a stranger's page.
See it running
Hero mode runs on our own home page. The character in the header is exactly this mechanism.