Add to Website

How to add it

Add your voice agent to any website using the Configure Widget dialog in your agent’s settings. Step 1: Open the agent settings by clicking the gear icon in the top-right of the agent editor. Open agent settings

Step 2: Scroll to the Add to Website section and click Configure Widget. Go to Add to Website

Step 3: Enable embedding, add your website’s domain to Allowed Domains, choose Floating Widget, Inline Component, or Headless (Bring Your Own UI), customize the button (position, color, text) if applicable, and click Save Configurations.

Step 4: Copy the generated embed code and paste it into your web page to test your agent. Copy deployment code

Embed modes

Mode	What it renders	When to use
Floating Widget	A pill-shaped CTA button anchored to a corner of the page.	You want a turn-key chat-bubble experience that doesn’t disturb your existing layout.
Inline Component	A panel rendered inside a `<div id="botrixai-inline-container">` that you place in your page.	You want the agent embedded in a specific section (landing-page hero, support tab, etc.).
Headless	No UI. Only the audio pipeline, driven from your own code.	You want full control over the UI — your own buttons, design system, framework state, animations.

Prerequisites

These apply to all three modes:

Serve your page over HTTPS or from http://localhost. Browsers refuse microphone access on plain HTTP origins or file://.
If you set Allowed Domains in the dashboard, include your test origin (e.g. localhost) — otherwise the widget’s config and signaling requests are rejected. Leave the list empty to allow all domains.
The embed snippet you copy from the dashboard is a single <script> tag that loads asynchronously. The widget initializes itself once the script arrives.

Floating widget shown in the corner of a host page

Renders a pill-shaped button (microphone icon + text) anchored to a corner of the page. Clicking it starts a call; clicking again ends it. The button auto-updates its label and color across the call lifecycle: configured text → “Connecting…” → “End Call” → “Retry” on failure. Configure Button Text, Button Color, and Position (top/bottom + left/right) from the dashboard. The host page writes no JavaScript — pasting the embed snippet is the entire integration.

Inline Component

Inline widget rendered inside a page section

Renders a panel (status icon + status text + CTA button) inside a <div> you place in your page. Status changes update the panel in place. Configure Button Text, Button Color, and Call to Action Text from the dashboard.

Plain HTML

Place a container <div> where you want the widget to render. The widget auto-attaches to it.

<!-- Paste the BotrixAI embed snippet from the dashboard somewhere on the page -->
<div id="botrixai-inline-container"></div>

React

React mounts after the widget script may already have loaded, so initialize via initInline on first mount and refresh on remount. Poll for window.BotrixAIWidget to handle the async script load.

import { useEffect } from 'react';

declare global {
  interface Window {
    BotrixAIWidget?: {
      initInline: (options: { container: HTMLElement }) => void;
      refresh: () => void;
      getState: () => { isInitialized: boolean };
    };
  }
}

export function Assistant() {
  useEffect(() => {
    let retries = 0;
    const tryInit = () => {
      const container = document.getElementById('botrixai-inline-container');
      if (window.BotrixAIWidget && container) {
        const { isInitialized } = window.BotrixAIWidget.getState();
        if (isInitialized) window.BotrixAIWidget.refresh();
        else window.BotrixAIWidget.initInline({ container });
      } else if (retries++ < 50) {
        setTimeout(tryInit, 100);
      }
    };
    tryInit();
  }, []);

  return <div id="botrixai-inline-container" />;
}

Headless Mode

In Headless mode the widget injects no UI of its own. You render whatever buttons, banners or in-call indicators you want, and call the JavaScript API to start and end calls.

JavaScript API

The widget exposes window.BotrixAIWidget once its script has loaded.

Method	What it does
`start()`	Begin a call.
`end()` / `stop()`	End the current call.
`retry()`	Retry after a failed connection.
`getState()`	Current widget state, including `isInitialized`.
`isInlineMode()`	`true` when the widget is in Inline mode.
`refresh()`	Re-render the inline panel — useful when a component remounts.
`initInline({ container })`	Attach the inline widget to an element yourself.

Call status moves through idle → connecting → connected → failed.

The embed script loads asynchronously, so window.BotrixAIWidget may not exist yet when your own code runs. Use optional chaining (?.) when registering callbacks, or poll for it as the React example above does.

Vanilla JS

Mirror the call status into a variable you control, then render whatever UI you like from it.

<button id="talk-btn">Talk to us</button>

<script>
  let callStatus = 'idle';

  window.BotrixAIWidget?.onStatusChange((status) => {
    callStatus = status;
    // ...trigger your render here (re-paint DOM, dispatch an event, etc.)
  });

  document.getElementById('talk-btn').addEventListener('click', () => {
    if (callStatus === 'connected' || callStatus === 'connecting') {
      window.BotrixAIWidget.end();
    } else {
      window.BotrixAIWidget.start();
    }
  });
</script>

React + TypeScript

import { useEffect, useState } from 'react';

type CallStatus = 'idle' | 'connecting' | 'connected' | 'failed';

declare global {
  interface Window {
    BotrixAIWidget?: {
      start: () => void;
      end: () => void;
      onStatusChange: (cb: (status: CallStatus) => void) => void;
    };
  }
}

export function TalkButton() {
  const [status, setStatus] = useState<CallStatus>('idle');

  useEffect(() => {
    window.BotrixAIWidget?.onStatusChange(setStatus);
  }, []);

  const isLive = status === 'connected' || status === 'connecting';

  return (
    <button
      onClick={() => (isLive ? window.BotrixAIWidget?.end() : window.BotrixAIWidget?.start())}
    >
      {isLive ? 'End call' : 'Talk to us'}
    </button>
  );
}

Lifecycle callbacks (all modes)

These work in Floating and Inline mode too, not just Headless — useful for analytics without changing how the widget looks.

window.BotrixAIWidget?.onReady(() => {/* widget loaded and configured */});
window.BotrixAIWidget?.onCallStart(() => {/* user started a call */});
window.BotrixAIWidget?.onCallConnected(() => {/* audio is flowing */});
window.BotrixAIWidget?.onCallDisconnected(() => {/* connection dropped */});
window.BotrixAIWidget?.onCallEnd(() => {/* call finished */});
window.BotrixAIWidget?.onStatusChange((status) => {/* any status change */});
window.BotrixAIWidget?.onError((error) => {/* something went wrong */});

Each callback holds one handler — registering a second replaces the first.

Getting started

Build your First Agent

Core Concepts

Configurations

Voice Agent Builder

Telephony

Integrations

How to add it

Embed modes

Prerequisites

Floating Widget

Inline Component

Plain HTML

React

Headless Mode

JavaScript API

Vanilla JS

React + TypeScript

Lifecycle callbacks (all modes)

​How to add it

​Embed modes

​Prerequisites

​Floating Widget

​Inline Component

​Plain HTML

​React

​Headless Mode

​JavaScript API

​Vanilla JS

​React + TypeScript

​Lifecycle callbacks (all modes)

How to add it

Embed modes

Prerequisites

Floating Widget

Inline Component

Plain HTML

React

Headless Mode

JavaScript API

Vanilla JS

React + TypeScript

Lifecycle callbacks (all modes)