Getting started

Learn how to integrate Odea AI avatars into your website with a few lines of code. Odea allows you to easily embed an AI avatar in your web app and interact with it through configurable options, handling events, and sending messages.

Quick Start Example

Here's a quick example of how to embed an Odea AI avatar directly into your HTML file:

<!-- index.html -->
<script type="module" defer src="https://odea.io/scripts/odea-embed.js"></script>
<script type="module">
  Odea.embed({ avatarId: "program:PETEEMBEDDEMO" });
</script>

This will embed the AI avatar using the avatarId provided, and start it automatically once it's ready.

Embed Options

For a detailed list of options, see the embed() method.

Example Usage

Here's how you can use the OdeaEmbedAPI to embed an avatar in your project.

Basic Example

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  onError(error) {
    console.error("An error occurred:", error);
  },
  onUserSpeech(speech) {
    console.log("User said:", speech);
  }
});

In this example:

• We embed an avatar with the ID program:PETEEMBEDDEMO.
• We set up a callback to handle errors, and log user speeches.
• The avatar interaction will begin automatically when it's ready.

Note: To control the start manually, use onReady and start() (see the "Starting the Chat Manually" section below).

Getting an Avatar ID

You can get an avatarId from Odea's platform. Users can create their own custom avatar or choose an existing one from Odea's collection or from avatars created by other users. To create or select an avatar:

1. Visit the Odea website and log in.
2. Navigate to the Avatars section.
3. Choose an avatar from the available collection or create your own personalized avatar.
4. Once selected or created, you will receive an avatarId that you can use to embed the avatar into your web project.

Each avatar has a unique avatarId, which you will use in the embed() method, as shown in the examples above.

Embed an Avatar in a Custom Container

If you want to embed the avatar in a specific container element rather than appending it to the body, you can provide a container parameter.

const containerElement = document.getElementById("avatar-container");

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  container: containerElement, // Inject embed into a specific DOM element
  embedClasses: "custom-class"
});

In this example, the avatar is embedded inside a specific container with a custom CSS class.

Starting a Chat Manually

By default, the chat interaction starts automatically once the avatar is ready. If you want full control over when the interaction begins, you can disable automatic start and use onReady with the start() method.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  options: {
    autoStart: false,  // Disable automatic start
  },
  onReady() {
    console.log("Avatar is ready. Starting interaction...");
    window.Odea.start();  // Start manually when ready
  },
});

⚠️ Important!

You should call this method only after the onReady() callback is triggered. If called before the avatar is ready, it will have no effect.

API Reference

The OdeaEmbedAPI allows you to embed an Odea avatar and interact with it via configuration options, events, and specialized callbacks.

Methods

embed(options: { ... }): void

Embeds an Odea avatar into the DOM and sets up event handlers.

start(): void

If you have disabled automatic start by setting autoStart to false, you should call this method to start the interaction with the AI avatar. You should call this method only after the onReady() callback is triggered. Otherwise, it will have no effect.

Events

The Odea embed emits events that you can listen to via callbacks provided in the embed function. Here's an overview of the available events and callbacks:

Handling Events

onReady

Triggered when the avatar is fully loaded and ready for interaction.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  onReady() {
    console.log("Avatar is ready.");
  }
});

onError

Called when an error occurs within the embed.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  onError(error) {
    console.error("An error occurred:", error);
  }
});

onStarted

Called when the avatar interaction has started.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  onStarted() {
    console.log("Started");
  },
});

onEnded

Called when the user has not interacted with the avatar within the specified timeoutMs. This resets the chat to its initial state. If startButton is set, the user may click on it to start again. Otherwise, call Odea.start() to start again.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  options: {
    timeoutMs: 60000  // Trigger onEnded after 60 seconds
  },
  onEnded() {
    console.log("User inactive. Resetting interaction.");
  },
});

onUserSpeech

Triggered when the user say something.

window.Odea.embed({
  avatarId: "program:PETEEMBEDDEMO",
  onUserSpeech(speech) {
    console.log("User speech:", speech);
  }
});