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) │
│ │ │ │
└─────────────────────┘ └─────────────────────┘
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>
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 |
<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>
With API Secret (for custom billing)
<script
src="https://agent.viewer.bithuman.ai/embed.js"
data-agent-id="A78WKV4515"
data-api-secret="your_api_secret"
></script>
Programmatic Control
// Initialize with options
window.bitHuman.init({
agentId: "A78WKV4515",
position: "bottom-right", // top-left, top-right, bottom-left, bottom-right, center
width: "400px",
height: "700px",
container: "#my-container", // Optional: embed in a specific element
});
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 *" |
Next Steps
