Get Started

Welcome to the developer docs!

Here you’ll find all the details on options, methods, and events for avatars created using the developer setup type. The no-code setup type is designed to be simple and intuitive, so if you’re using that, you likely won’t need this documentation.

iFrame Implementation

How it works

The JavaScript library provides a simple, secure, and flexible way to embed and control a fully interactive 3D AI avatar on your website using a single function call.

When you include the provided <script> snippet, it loads the required library hosted by our CDN. This handles authentication, iframe creation, and postMessage-based communication between your site and the avatar engine running remotely inside a sandboxed iframe.

Both Type 1 and Type 2 avatars can be initialized using the same method. However, because iframe-based rendering introduces additional communication latency, Type 2 avatars are also available through our JavaScript SDK. The SDK initializes the avatar engine directly within the client environment, bypassing iframe postMessage communication to deliver low-latency, real-time facial tracking, animation control, and direct access to camera or avatar media streams. These streams can then be integrated into any WebRTC based service, such as LiveKit, Twilio Video, Agora etc, allowing you to replace a user’s live video feed with their animated avatar.

Initialization & Authentication

The primary entry point is the loadAvatar(params) function.

You pass it a configuration object containing your API key, desired avatar options, and setup preferences (like width, height etc).

Example 
<!-- Avatar container -->
<div id="avatar-container" style="width:600px; height:500px;"></div>
<!-- Load the library -->
<script src="https://interactiveavatar.co.uk/loadAvatar_v1.0.min.js"></script>
<script>
  window.addEventListener('load', () => {
    if (typeof loadAvatar !== "function") {
      console.error("Avatar library not loaded yet.");
      return;
    }
    loadAvatar({
      setup: {
        key: "YOUR API KEY",
        elementId: "avatar-container",
        debug: false
      },
      avatar: {
        glb: "https://example.com/hero.glb",
        type: 1
      },
      chat: {
        showChat: true,
        showChatInput: true
      }
    })
    .then((interactiveAvatar) => {
      console.log("API ready, methods available", interactiveAvatar);
    })
    .catch(err => console.error("Avatar failed to load:", err));
  });
</script>

Before rendering your avatar, your API key is validated along with any HTTPS referrer options you may have set in your profile area, then the iframe is created and initialized.

To see all available options, refer here.

The Control Object (interactiveAvatar)

Once the iframe loads successfully, the loadAvatar() Promise resolves with an interactive control object.

This object serves as your API bridge to the avatar inside the iframe.

Example 
loadAvatar(config).then(interactiveAvatar => {
  interactiveAvatar.speak({
    text: "Hello, world!"
  });
});

Methods are executed via window.postMessage() from the iframe, using a simple { type, options } pattern. Such methods include:

  • loadAvatar – loads a new avatar
  • setView / setMood – set the view/mood of the avatar
  • sendMessage – communicate with the avatar by typing a message instead of speaking
  • speak – allows the avatar to speak some text that you define

To see all of the available methods, refer here.

Event System

The library includes a lightweight event listener system for receiving asynchronous updates from the iframe.

Use .on(eventType, callback) to subscribe:

Example 
interactiveAvatar.on("avatarReady", (event) => {
  console.log("Avatar is ready!", event.data);
});

Events are triggered via window.postMessage() from the iframe and include updates such as:

  • avatarReady – the avatar has initialized
  • speechStarted / speechEnded – speech state changes
  • animationCompleted – when a triggered animation finishes
  • conversationUpdated – AI response or chat update events

To see all of the available events, refer here.

Debugging and Logging

If setup.debug is set to true, the library will log:

  • Initialization parameters (with key redacted)
  • The generated iframe URL
  • Element attachment information
  • Other logging information when you interact

This helps verify that your configuration and environment are correct during integration.