How to Add an AI Avatar to Your Website

An AI avatar can sit inside a product demo, onboarding flow, support page, or digital concierge. The simplest setup takes one script tag. A custom integration gives you control over the interface and session logic.

If you are new to the technology, start with What Is an Interactive AI Avatar?.

Before you add the code

Choose the moment when the avatar should appear. A pricing page might use one to answer product questions. An onboarding screen might use one to guide a new customer through setup.

Give the visitor a clear start button. Browsers require permission before giving a page microphone access,^[1] and media playback may be restricted without recent user activation.^[2] A Start button gives both permissions and playback an intentional moment.

Option 1: Add the hosted avatar embed

This is the fastest path for a standard video panel.

1. Create a publishable key

Create a publishable key in the Casola dashboard and add your website origin, such as https://example.com, to its allowed origins. Publishable keys are limited to starting sessions and are safe to place in browser code.

Do not put a secret API key in your HTML. Secrets embedded in client-side code can be extracted and reused outside your application.^[3]

2. Add one script tag

Place this where you want the avatar to appear:

<script
  src="https://www.casola.ai/widget.js"
  data-key="pk_your_publishable_key"
  data-avatar="david"
  data-lang="en">
</script>

The script inserts a responsive 16:9 avatar panel with its own Start button. Change data-avatar to the persona you want and data-lang to the conversation language.

You can size the outer element with normal CSS:

avatar-embed {
  width: min(100%, 960px);
  margin-inline: auto;
}

Option 2: Build a custom interface

Use the @casola/avatar-client package when the avatar needs to match your product UI or react to application state.

The secure connection has two parts:

1. Your server uses a secret key to create a short-lived avatar session.
2. The browser receives the temporary connect_url and session_token, then connects with AvatarSession.

Your secret key stays on the server. The browser SDK handles live video playback, microphone streaming, turn events, interruptions, and session cleanup.

npm install @casola/avatar-client

From there, connect the SDK to a <video> element and call session.start() from a button click. Casola’s developer quickstart includes the complete server and browser examples.

Test the experience before launch

Check the integration on desktop and mobile. Test what happens when someone denies microphone permission, has a slow connection, or ends the call early. The page should explain each state and always provide a clear way to leave the session.

Keep the avatar focused on one job. A sales assistant should answer product questions; an onboarding guide should help with setup. A narrow role produces a clearer conversation and makes it easier to measure whether the avatar is helping.

Frequently asked questions

Sources

1. World Wide Web Consortium. Media Capture and Streams. W3C Recommendation.
2. WHATWG. HTML Standard: Media Elements. Living Standard.
3. OWASP Foundation. Secrets Management Cheat Sheet. OWASP Cheat Sheet Series.