Put a talking avatar on your website

Every avatar has its own ID. Its face, voice and character come ready from the studio. You add one line of code and set your own rules on your side.

Quick start

1. Sign in to the studio, create an avatar and save it to the library.
2. Open your account menu → Developer API. Turn the avatar on and add your website domain to Allowed websites.
3. Copy the embed code and paste it before </body> on your site.

<script src="https://mavatora.com/embed.js"
        data-avatar-id="AVATAR_ID"
        data-key="SITE_KEY"
        async></script>

That's it: a round button with the avatar's photo appears in the corner. Visitors click it and talk by voice.

Key only. data-avatar-id is optional. Without it, the first avatar you enabled in Developer API is used:

<script src="https://mavatora.com/embed.js" data-key="SITE_KEY" async></script>

Install options

1. Floating button

The code above. Add data-position="left" to put it on the left, data-label="Ask Anna" to change the label, data-open="true" to open it on page load.

2. Inline block

The avatar fills any element you choose. Give the element a size.

<div data-talking-avatar="AVATAR_ID" data-key="SITE_KEY"
     data-greeting="Hi! Ask me anything about our store."
     style="width:380px;height:560px;border-radius:20px;overflow:hidden"></div>
<script src="https://mavatora.com/embed.js" async></script>

3. JavaScript (full control)

<script src="https://mavatora.com/embed.js"></script>
<script>
  const avatar = TalkingAvatar.mount({
    avatarId: "AVATAR_ID",
    key: "SITE_KEY",
    target: "#avatar",          // omit for a floating button
    greeting: "Hi! How can I help you today?",
    rules: "You are the assistant of Acme Store. Answer only about our products.",
    context: "Opening hours: Mon–Fri 9–18. Free delivery over $50.",
    lang: "English"
  });
  avatar.on("live", active => console.log("conversation", active));
</script>

Works with any site: plain HTML, WordPress (Custom HTML block or footer scripts), Shopify (theme.liquid), Webflow, Wix, Tilda, React, Vue, Next.js.

React

useEffect(() => {
  const s = document.createElement("script");
  s.src = "https://mavatora.com/embed.js";
  s.onload = () => { ref.current = window.TalkingAvatar.mount({ avatarId, key, target: boxRef.current, rules }); };
  document.body.appendChild(s);
  return () => ref.current?.destroy();
}, []);

Options

Rules & context

The avatar already has a face, voice and base character from the studio. Rules and context are added on top for your website only — you can use one avatar on several sites with different rules.

rules: `You are Anna, the online consultant of Acme Store.
- Answer only questions about our products, delivery and returns.
- If you don't know the answer, offer to connect the visitor with a manager.
- Never promise discounts.
- Keep answers to 1–3 sentences.`

Change rules at any time without reloading: avatar.setRules("..."), avatar.setContext("..."). New rules apply from the next conversation.

Methods & events

The floating widget created from HTML attributes is available as TalkingAvatar.widget. Inline avatars from attributes are available as element.__talkingAvatar.

Security

• The site key is public — it is visible in your page code. It is protected by Allowed websites: the avatar only works on the domains you list (subdomains included). Always fill this list in.
• Only avatars you switched on in Developer API can be used with your key.
• If a key leaks, press Regenerate — the old key stops working immediately.
• Our Gemini voice key never leaves our servers; each conversation gets a one-time token valid for 30 minutes.

Plans & limits

One conversation = one press of “Talk” (up to 30 minutes). The counter resets on the 1st of each month. To change your plan, contact ceo@fitofan.com.

REST API

For custom players and mobile apps. All endpoints allow cross-origin requests.

GET /api/v1/avatar

GET https://mavatora.com/api/v1/avatar?id=AVATAR_ID&key=SITE_KEY

200 { "id": "…", "name": "Anna", "gender": "f", "layout": "mobile",
      "thumb": "https://…/thumb.jpg", "data": "https://…/data.json" }

POST /api/v1/session

Returns a one-time Gemini Live token for a voice conversation with this avatar. Counts as one conversation.

POST https://mavatora.com/api/v1/session
Content-Type: application/json

{ "avatar": "AVATAR_ID", "key": "SITE_KEY" }

200 { "token": "auth_tokens/…" }

The easiest custom integration is still the iframe the widget uses:

<iframe src="https://mavatora.com/embed.html?avatar=AVATAR_ID&key=SITE_KEY&lang=English"
        allow="microphone; autoplay" style="width:380px;height:560px;border:0"></iframe>

Control it with postMessage: {type:"avatar:start"}, {type:"avatar:stop"}, {type:"avatar:ask", text}, {type:"avatar:config", rules, context, greeting}. It sends back avatar:loaded, avatar:live, avatar:status, avatar:error.

Errors

FAQ

The microphone doesn't work

Your site must use https://. If you add the iframe yourself, keep allow="microphone; autoplay".

Can I use one avatar on several websites?

Yes. Add all domains to Allowed websites and give each site its own rules.

Does it work on mobile?

Yes. On phones the floating panel opens full screen.