Website widget

6 steps

1. Pick the agent

   Use the wise-pup sample (agent code A23WJF0199) while you build. For your own agent, keep Let anyone talk without signing in on in the agent’s Share Agent dialog: the widgets open the agent’s public link, and its sessions bill your account.

   Sample agents end after 1 minute. bitHuman pays for sessions on its sample and showcase agents, such as wise-pup, so each one ends about a minute after the avatar appears (or 5 minutes after it starts, if the avatar never appears), with an end-of-demo card.

   Your own agent has no visitor limits by default. Chats run until the visitor closes them and bill by the second, talking or idle; set a limit for a kiosk that runs all day. You can set a per-session and a daily limit. Sessions start only when the visitor taps, so a page view costs nothing.

   Set them in the Console: open the agent’s Embed Agent tab, then Visitor limits, to set a daily limit in minutes for all visitors together, a limit per chat (5 to 60 minutes, or no limit) and an optional list of allowed websites. When the daily limit is used up, new visitors see a Resting for Today card until the next day.

   Expected

   https://bithuman.ai/A23WJF0199 opens the avatar in a browser tab.

   Done: step 1

2. Add the floating widget

   Paste this before </body>:

   <script src="https://www.bithuman.ai/widgets/bithuman-gadget.js"></script>
   <script>
     BitHumanGadget.init({
       agentUrl: "https://bithuman.ai/A23WJF0199?deployment=gadget&render=auto",
       position: "bottom-right",
       buttonText: "Talk to us",
     });
   </script>

   render=auto: web render by default; devices that can’t web-render use cloud render automatically. render=cloud forces cloud.

   Expected

   A button in the bottom-right corner. Select it: the avatar opens in a floating frame you can drag and resize, asks for the microphone, and answers when you speak.

   Done: step 2

3. Or add the chat widget

   The chat widget opens a side panel where visitors type, talk, or switch to video:

   <script src="https://www.bithuman.ai/widgets/bithuman-chat-widget.js"></script>
   <script>
     BitHumanChat.init({
       agentUrl: "https://bithuman.ai/A23WJF0199?render=auto",
       defaultChatMode: "text",
       welcomeMessage: "Hi! How can I help?",
     });
   </script>

   Expected

   A floating card in the corner. Opening it shows the panel with the welcome message; the mode switch moves between text, voice and video.

   Done: step 3

4. Make the AI character stand on your page

   Add transparent: true and the character’s backdrop is removed, so it floats over your page with no box around it. Try it with the Biscuit sample (agent code G10BISCUIT):

   <script src="https://www.bithuman.ai/widgets/bithuman-gadget.js"></script>
   <script>
     BitHumanGadget.init({
       agentUrl: "https://bithuman.ai/G10BISCUIT?deployment=gadget&render=auto",
       transparent: true,
       size: 360,
     });
   </script>

   Expected

   The button opens Biscuit standing directly on your page, with your page's background around it.

   Transparent mode works for AI characters filmed or generated on a plain green backdrop. For any other character the frame stays as it is, so turning it on never breaks a page. In your own <iframe>, add transparent=1 to the embed URL instead.

   Done: step 4

5. Load it in React or Next.js

   In Next.js, load the script with next/script and call init when it has loaded:

   "use client";
   import Script from "next/script";
   
   declare global {
     interface Window { BitHumanGadget?: { init: (options: Record<string, unknown>) => void } }
   }
   
   export function AvatarWidget({ code }: { code: string }) {
     return (
       <Script
         src="https://www.bithuman.ai/widgets/bithuman-gadget.js"
         strategy="afterInteractive"
         onLoad={() => window.BitHumanGadget?.init({ agentUrl: `https://bithuman.ai/${code}?deployment=gadget&render=auto` })}
       />
     );
   }

   Render <AvatarWidget code="A23WJF0199" /> once, in your root layout. In other React apps, add the two <script> tags to the page’s HTML, or put the web embed in an <iframe> (Web).

   Expected

   The widget's button appears on every page of the app. A second init call is ignored, so a re-render does not add a second widget.

   Done: step 5

6. Give it your persona and model

   The widget runs the agent’s managed conversation, so the persona and the model are settings on the agent, not code on your page. Set the persona as the agent’s system_prompt (Persona). To answer with your own model, connect any OpenAI-compatible endpoint with Providers and point the agent’s llm at it.

   Expected

   The next session answers in the new persona, with your model. Nothing on your page changed.

   Done: step 6

All steps done. Next: make it your own.