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 Chat Bubble Widget 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:
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.
Chat Bubble Widget
Instead of placing the sidekick inline, you can float it as a bubble in the corner of every page — the pattern most support chat widgets use. Visitors see a circular avatar with a short greeting; clicking it expands a compact chat panel.
src="https://sidekickforge.com/static/js/widget-launcher.js"
data-client="YOUR_CLIENT_ID"
data-agent="YOUR_SIDEKICK_SLUG"
async></script>
Paste it once before the closing </body> tag on any page that should
show the bubble. It supports all three modes — text, voice and video — in a
smaller frame, and takes over the full screen on phones where a 400px panel would be
unusable.
Customising the bubble
Appearance lives on the sidekick itself, under Connections → Chat Bubble Widget — greeting text, screen position, accent colour, bubble size, how long before the greeting appears, and whether it opens automatically. Changes take effect within a few minutes; the config is cached.
Performance
The script is small and the chat panel is only loaded when a visitor first opens it, so pages where nobody clicks pay almost nothing. One sidekick per page is supported.
Basic iframe Embed
The simplest way to add your sidekick to any webpage. Just paste this HTML where you want the sidekick to appear:
src="https://sidekickforge.com/embed/YOUR_CLIENT_ID/YOUR_SIDEKICK_SLUG"
style="border: 0; width: 100%; min-height: 600px;"
allow="microphone; camera"
></iframe>
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:
WordPress Shortcode
If you're using the Sidekick Forge Connect plugin, use the built-in shortcode for automatic WordPress authentication:
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. |
width | 100% | Width of the embed container. |
height | — | Fixed height (overrides min_height). |
min_height | 600px | Minimum 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:
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:
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.