Docs
Docs / Embedding

Embedding Your Sidekick

Deploy your AI sidekick on any website with a simple embed code. Supports text chat, voice conversations, and video mode out of the box.

On this page

Your Embed URL Basic iframe Embed WordPress Shortcode Chat Modes Fullscreen Support React Component (Advanced)

Your Embed URL

Each sidekick has a unique embed URL based on your client ID and the sidekick's slug:

# Embed URL format
https://sidekickforge.com/embed/{client_id}/{sidekick_slug}

You can find this URL on the sidekick detail page in the admin panel under the Embed tab.

Sidekick Detail — Configuration
Sidekick Detail Page

Basic iframe Embed

The simplest way to add your sidekick to any webpage. Just paste this HTML where you want the sidekick to appear:

<iframe
  src="https://sidekickforge.com/embed/YOUR_CLIENT_ID/YOUR_SIDEKICK_SLUG"
  style="border: 0; width: 100%; min-height: 600px;"
  allow="microphone; camera"
></iframe>
Important: The allow="microphone; camera" attribute is required for voice and video modes. Without it, the browser will block microphone access inside the iframe.

Recommended Sizing

The embed is fully responsive. Here are recommended minimum dimensions for each mode:

Text Chat
400 × 500
px minimum
Voice Chat
400 × 600
px minimum
Video Chat
500 × 700
px minimum

WordPress Shortcode

If you're using the Sidekick Forge Connect plugin, use the built-in shortcode for automatic WordPress authentication:

[sidekick_forge_embed
  src="https://sidekickforge.com/embed/YOUR_CLIENT_ID/YOUR_SIDEKICK_SLUG"
  width="100%"
  min_height="600px"]

The shortcode accepts these attributes:

Attribute Default Description
src—Required. The embed URL for your sidekick.
width100%Width of the embed container.
height—Fixed height (overrides min_height).
min_height600pxMinimum height of the embed.
aspect—Aspect ratio (e.g., 16/9 or 4/3).
class—Additional CSS classes for the iframe.

Chat Modes

The embed supports three interaction modes, toggled via icons in the header:

Text
Classic chat interface with streaming responses, citations, and markdown formatting.
Voice
Real-time voice conversation with live transcription, audio visualizer, and turn detection.
Video
Face-to-face mode with an animated avatar. Powered by BitHuman or Ken Burns image animation.
You can control which modes are available per sidekick from the sidekick configuration page. If only text is enabled, the mode toggle won't appear.

Fullscreen Support

The embed includes a built-in fullscreen button next to the mode toggle. When activated, the embed expands to fill the entire screen. Users can exit fullscreen with the same button or by pressing Esc.

Fullscreen mode works with all three chat modes and includes the conversation history overlay.

React Component (Advanced)

For deeper integration in React applications, you can use the connection details API to build a custom UI:

// Fetch connection details
const response = await fetch(
  `/api/embed/connection-details/${clientId}/${agentSlug}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const { serverUrl, roomName, participantToken } = await response.json();

// Connect with LiveKit React Components
<LiveKitRoom
  serverUrl={serverUrl}
  token={participantToken}
  connect={true}
/>

This approach gives you full control over the UI while using Sidekick Forge's backend for AI processing, voice synthesis, and knowledge retrieval.

Previous ← Knowledge Base Guide