Add a MeshLite avatar to your site

The avatar runs in an iframe served by MeshLite and is rendered in your visitor’s browser. Your page loads one script, your server issues short-lived session tokens, and voice and AI come from your own provider account.

Add a MeshLite talking avatar to this website. Follow the guide at https://meshlite.io/llms.txt (if you can't open it, ask me to paste it). Ask me for my MeshLite publishable key and, optionally, an avatar ID. Never ask me to paste my secret key: put a placeholder in .env and I'll add it myself. If I don't have a MeshLite account, send me to https://console.meshlite.io/console?plan=free#signup first.

1Create your workspace

Sign up in the Console: free, no card, activated from the email we send. The Free plan is for building and testing: localhost and staging domains, the default avatars, a MeshLite badge on the avatar, up to 3 simultaneous conversations and a one-time voice trial. Going live on your production domain needs a paid plan.

2Set up the Console

• Domains: add every origin that will show the avatar, exactly as the browser sees it, port included: http://localhost:3000 for local development, https:// for anything else.
• API keys: create a publishable key and a secret key in the same environment. Test keys (ml_pk_test_…) work with test domains; live keys with live domains.
• Voice & TTS: connect your voice provider with your own key: OpenAI, Azure OpenAI Realtime, Azure AI Speech or ElevenLabs. The Free voice trial uses the MeshLite voice; after it, conversations need your provider.
• Personalities: write what the avatar knows and how it speaks, publish it and assign it to your avatar and website.
• Integration: copy your avatar ID. This page also shows the code below with your own values filled in.

Then add them to your server’s environment. The secret key never goes in browser code or Git.

MESHLITE_SECRET_KEY=ml_sk_test_...
MESHLITE_PUBLISHABLE_KEY=ml_pk_test_...
MESHLITE_ORIGIN=http://localhost:3000
MESHLITE_AVATAR=

3Issue session tokens from your server

Your server keeps the secret key and asks MeshLite for a session token. Call this from a POST /api/meshlite-session route and return { sessionToken }. Tokens last 2 minutes; the SDK asks for a new one when it needs it. Node.js 18+, no dependency:

export async function createMeshLiteSession() {
  const response = await fetch("https://console.meshlite.io/api/v1/client-sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MESHLITE_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      publishableKey: process.env.MESHLITE_PUBLISHABLE_KEY,
      origin: process.env.MESHLITE_ORIGIN, // from your config, never from the request
      avatar: process.env.MESHLITE_AVATAR || undefined,
      conversation: { language: "en", responseStyle: "concise", idleTimeout: 30 },
    }),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`MeshLite ${body.error?.code}: ${body.error?.message}`);
  return body.sessionToken;
}

The route is public: rate-limit it, or put it behind your own sign-in if only signed-in users should talk to the avatar.

4Mount the avatar in your page

The iframe takes the size of its container. Browsers only open the microphone after a click, so start the conversation from one.

<div id="avatar" style="width:340px;height:510px"></div>
<button id="talk">Talk to the avatar</button>
<script src="https://console.meshlite.io/sdk/1.11.39/meshlite.js" crossorigin="anonymous"></script>
<script>
  const avatar = MeshLite.mount({
    container: "#avatar",
    avatar: "YOUR_AVATAR_ID",          // same as MESHLITE_AVATAR; remove for the default avatar
    locale: "en",
    publishableKey: "ml_pk_test_...",  // safe to expose
    sessionToken: async () => {
      const response = await fetch("/api/meshlite-session", { method: "POST" });
      if (!response.ok) throw new Error("Could not start the avatar session");
      return (await response.json()).sessionToken;
    },
    conversation: { language: "en", responseStyle: "concise", idleTimeout: 30 },
    captions: "overlay",
  });
  avatar.on("error", (message, detail) => console.error("MeshLite", detail.code, message));
  document.getElementById("talk").addEventListener("click", () => avatar.startConversation());
</script>

React, Next.js, Vue: load the script once, mount in a client-side effect (useEffect, onMounted) and call avatar.unmount() in its cleanup. There is no npm package: load the SDK from console.meshlite.io only.

Going live

Move to a paid plan, add your production domain as a live domain (HTTPS), create live keys and replace the test values in your environment. No code change is needed.

Reference

• Versions: the current SDK is 1.11.39. Pin an exact version; the Console’s Integration page always shows the current one. Only the three latest versions are served, and older version URLs redirect to the current one.
• Types: https://console.meshlite.io/sdk/1.11.39/meshlite.d.ts
• Content Security Policy: if your site has one, allow https://console.meshlite.io in script-src and frame-src. If you send a Permissions-Policy header, allow the microphone for that origin too.
• Browsers: HTTPS is required in production. Older browsers that can’t run the avatar show an idle preview only; check MeshLite.supportsConversation().
• Common errors: ORIGIN_NOT_ALLOWED means the page’s origin (port included) is not registered in the keys’ environment; ENVIRONMENT_MISMATCH means a test key is paired with a live key; PLAN_STAGING_ONLY means the Free plan cannot add a live domain; VOICE_PROVIDER_REQUIRED means no voice provider is connected. The full guide lists every option, event and error.

Questions about your integration? Write to hello@meshlite.io.