The Embedded Widget
The embedded widget lets you put a Corral-powered chat interface on any website — your customer-facing site, an internal portal, a help center, or any web page.
How It Works
The widget is a lightweight JavaScript snippet you add to your page. It loads a chat interface that connects to your Corral instance via DirectLine WebSocket. Users interact with whatever agent you’ve configured for that app, with the same intelligence, tools, and guardrails as any other channel.
Setting Up the Widget
- Navigate to your app in the admin console
- Open the Channels tab
- Select Web Chat Widget
- Configure the widget appearance and behavior
- Copy the embed snippet
- Add the
<script>tag to your website
Configuration Options
| Option | What It Controls |
|---|---|
| Position | Where the widget appears on the page (corner placement) |
| Colors | Widget chrome, chat bubble, text colors |
| Fonts | Typography for the chat interface |
| Avatars | Agent and user avatars displayed in the chat |
Domain Whitelisting
For security, you specify which domains are allowed to host the widget. The widget only loads on whitelisted domains. This prevents unauthorized sites from embedding your agent.
Embedding
The embed snippet looks like a standard <script> tag. Add it to your page’s HTML:
<!-- Get the exact snippet from your admin console -->
<script src="https://[your-instance]/widgets/webchat/[app-id]"></script>The snippet handles everything — loading the widget, establishing the DirectLine connection, and rendering the chat interface.
API Endpoints
If you need programmatic access to widget configuration:
GET /api/envs/{'{'}env{'}'}/apps/{'{'}appId{'}'}/widgets/webchat/config— retrieve widget configurationGET /api/apps/{'{'}slug{'}'}/widgets/webchat/snippet— get the embed snippet
What Users See
The widget appears as a chat bubble on your page. Clicking it opens a chat interface where users interact with the configured agent. The experience is a contained version of the Hub — real-time messaging, streamed responses, and whatever tools the agent has access to.
This section is a work in progress.
Governance
The widget is a channel like any other. All interactions go through the same intelligence configuration, tool access controls, and analytics as the Hub or Teams channels. Widget conversations appear in the app’s analytics and activity logs in the admin console.