Embed Avatars on Any Website (iframe)

Embed a bitHuman avatar directly on your website so visitors can have real-time conversations without leaving your page.

How Embedding Works

Your Website                          bitHuman Cloud
┌─────────────────────┐              ┌─────────────────────┐
│                     │              │                     │
│  <iframe>           │  ◄──────►   │  Avatar Session     │
│    Avatar Widget    │   WebRTC    │  (video + audio)    │
│  </iframe>          │              │                     │
│                     │              │  AI Agent           │
│  Your page content  │              │  (conversation)     │
│                     │              │                     │
└─────────────────────┘              └─────────────────────┘

The avatar runs entirely in bitHuman’s cloud. Your website just needs a small embed snippet.

Quick Start (Zero Config)

The simplest way to embed an agent — one line of HTML, no backend needed:

<iframe
  src="https://agent.viewer.bithuman.ai/api/embed/YOUR_AGENT_CODE"
  allow="microphone *; camera *; autoplay *"
  style="width: 400px; height: 700px; border: none; border-radius: 12px;"
></iframe>

Replace YOUR_AGENT_CODE with your agent’s code (e.g. A78WKV4515). Find it in the Library or the Deploy & Share dialog.

Customize with URL Parameters

Parameter	Example	Description
`chat_mode`	`text`	Start in text-only mode (`text`, `voice`, or `video`)
`greetingLang`	`de`	Greet in a specific language (ISO 639-1 code)
`greetingMsg`	`Hello!`	Custom greeting message
`embed_theme`	`light`	Widget theme (`light` or `dark`)
`theme_color`	`blue`	Accent color (`blue`, `purple`, `green`, `red`, `orange`, `teal`, `pink`, `indigo`)
`welcomeMsg`	`Hi there!`	Custom welcome message
`suggestedQuestions`	`["How can I help?"]`	JSON array of suggested question chips
`model`	`essence`	Avatar model type (`essence` or `expression`)
`deployment`	`chat-widget`	Deployment context (`chat-widget`, `gadget`, `iframe`)

<iframe
  src="https://agent.viewer.bithuman.ai/api/embed/A78WKV4515?chat_mode=text&greetingLang=de"
  allow="microphone *; camera *; autoplay *"
  style="width: 400px; height: 700px; border: none; border-radius: 12px;"
></iframe>

The embed endpoint generates a session token automatically. No API secret or backend is needed. Sessions don’t expire — the embedded agent works indefinitely.

Advanced: Token-Based Embed

For more control (e.g. custom billing, session tracking), generate tokens from your backend:

Generate an embed token

Call the embed token API from your backend (never expose your API secret in the browser):

import requests

resp = requests.post(
    "https://api.bithuman.ai/v1/embed-tokens/request",
    headers={"api-secret": "your_api_secret"},
    json={
        "agent_id": "A78WKV4515",
        "fingerprint": "unique-visitor-id",
    },
)
data = resp.json()["data"]
token = data["token"]       # JWT token
session_id = data["sid"]    # Session identifier

Embed in your page

Use the token to load the avatar widget:

<iframe
  src="https://agent.viewer.bithuman.ai/A78WKV4515?token=TOKEN_HERE&sid=SESSION_ID"
  allow="microphone *; camera *; autoplay *"
  style="width: 400px; height: 700px; border: none; border-radius: 12px;"
></iframe>

Never put your API secret in frontend code. Always generate embed tokens from your backend server. The API secret grants full access to your account.

For a floating chat button that opens an avatar panel, use embed.js:

<script
  src="https://agent.viewer.bithuman.ai/embed.js"
  data-agent-id="A78WKV4515"
></script>

No API secret needed — the script uses the zero-config embed endpoint automatically. The widget appears as a floating button in the bottom-right corner.

With API Secret (server-rendered pages only)

If you need usage billed to your account, pass the API secret — but only on server-rendered pages where the HTML is generated on your backend. Never include your API secret in a public static HTML file or client-side JavaScript.

<!-- Server-rendered only — do NOT use in static HTML or SPA bundles -->
<script
  src="https://agent.viewer.bithuman.ai/embed.js"
  data-agent-id="A78WKV4515"
  data-api-secret="your_api_secret"
></script>

For client-side apps, use the embed token flow above instead.

Programmatic Control

// Initialize with options
window.bitHuman.init({
  agentId: "A78WKV4515",
  position: "bottom-right",    // top-left, top-right, bottom-left, bottom-right, center
  width: "320px",
  height: "180px",
  container: "#my-container",  // Optional: embed in a specific element
});

For a full-featured floating chat interface with text, voice, and video modes:

<script src="https://www.bithuman.ai/bithuman-chat-widget-v5.js"></script>
<script>
  BitHumanChat.init({
    agentUrl: 'https://bithuman.ai/YOUR_AGENT_CODE',
    theme: 'light',
    themeColor: 'blue',
    fabText: 'Ask me anything...',
    defaultChatMode: 'text',
    welcomeMessage: 'Hi! How can I help you today?',
    suggestedQuestions: [
      'What services do you offer?',
      'How does pricing work?',
    ],
  });
</script>

Configuration Options

Option	Type	Default	Description
`agentUrl`	string	required	Full agent URL (e.g. `https://bithuman.ai/A78WKV4515`)
`theme`	string	`"light"`	`"light"` or `"dark"`
`themeColor`	string	`"blue"`	Accent color: `blue`, `purple`, `green`, `red`, `orange`, `teal`, `pink`, `indigo`
`position`	string	`"bottom-right"`	Widget position: `"bottom-right"` or `"bottom-left"`
`fabStyle`	string	`"bar"`	Button style: `"bar"` (text + avatar) or `"circle"` (avatar only)
`fabText`	string	`"Ask me anything..."`	Text shown on the bar-style button
`defaultChatMode`	string	`"text"`	Default mode: `"text"`, `"voice"`, or `"video"`
`allowModeSwitch`	boolean	`true`	Allow users to switch between text, voice, and video
`welcomeMessage`	string	`""`	Welcome message shown when chat opens
`suggestedQuestions`	string[]	`[]`	Up to 3 clickable question suggestions
`panelWidth`	number	`380`	Chat panel width in pixels
`panelHeight`	number	`540`	Chat panel height in pixels

Public Methods

BitHumanChat.open();        // Open the chat panel
BitHumanChat.close();       // Close to floating button
BitHumanChat.isOpen();      // Returns true if panel is open
BitHumanChat.setTheme('dark');  // Switch theme
BitHumanChat.destroy();     // Remove widget completely

The widget automatically fetches the agent’s avatar image for the floating button. No manual image configuration needed.

For a customizable floating button with avatar thumbnail:

<script src="https://www.bithuman.ai/bithuman-web-gadget.js"></script>
<script>
  BitHumanGadget.init({
    agentUrl: "https://bithuman.ai/A78WKV4515?deployment=gadget",
    buttonStyle: "pill",       // pill, circle, square
    position: "bottom-right",
    theme: "light",            // light, dark
    size: 200,
    draggable: true,
    resizable: true,
  });
</script>

Customization

Responsive Sizing

<div style="position: relative; width: 100%; max-width: 500px; aspect-ratio: 1;">
  <iframe
    src="https://agent.viewer.bithuman.ai/A78WKV4515?token=TOKEN"
    allow="microphone; camera"
    style="
      position: absolute;
      top: 0; left: 0;
      width: 100%; height: 100%;
      border: none;
      border-radius: 12px;
    "
  ></iframe>
</div>

Control the Avatar from Your Page

Use the REST API to send messages to an active avatar session:

// Make the avatar say something
await fetch("https://api.bithuman.ai/v1/agent/A78WKV4515/speak", {
  method: "POST",
  headers: {
    "api-secret": API_SECRET,  // Call from backend!
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Welcome! How can I help you today?",
  }),
});

Troubleshooting

Problem	Solution
Blank iframe	For zero-config embed, check that your agent code is correct. For token-based, verify token is valid.
No audio	Ensure `allow="microphone "` is set on the iframe (note the `` for cross-origin)
CORS errors	Use the zero-config embed URL (`/api/embed/CODE`) which handles CORS automatically
Avatar not responding	Check agent exists in your Library and has status “Ready”
iframe blocked	Some browsers block third-party iframes. Add `allow="microphone ; camera ; autoplay *"`

Getting Started

Swift SDK

Deployment

Integrations

Changelog

Embed Avatars on Any Website (iframe)

How Embedding Works

Quick Start (Zero Config)

Customize with URL Parameters

Advanced: Token-Based Embed

embed.js Widget

With API Secret (server-rendered pages only)

Programmatic Control

Chat Widget

Configuration Options

Public Methods

Gadget Widget (Legacy)

Customization

Responsive Sizing

Control the Avatar from Your Page

Troubleshooting

Next Steps

Webhooks

Agent Context API

Getting Started

Swift SDK

Deployment

Integrations

Changelog

Documentation Index

​How Embedding Works

​Quick Start (Zero Config)

​Customize with URL Parameters

​Advanced: Token-Based Embed

​embed.js Widget

​With API Secret (server-rendered pages only)

​Programmatic Control

​Chat Widget

​Configuration Options

​Public Methods

​Gadget Widget (Legacy)

​Customization

​Responsive Sizing

​Control the Avatar from Your Page

​Troubleshooting

​Next Steps

Webhooks

Agent Context API

How Embedding Works

Quick Start (Zero Config)

Customize with URL Parameters

Advanced: Token-Based Embed

embed.js Widget

With API Secret (server-rendered pages only)

Programmatic Control

Chat Widget

Configuration Options

Public Methods

Gadget Widget (Legacy)

Customization

Responsive Sizing

Control the Avatar from Your Page

Troubleshooting

Next Steps