Chat Widget & SDK
The Outrun chat widget embeds an AI-powered chat interface on your website. Visitors interact with your configured agents directly from your site. The SDK handles widget rendering, message delivery, and optional visitor identification.
Installation
Add the SDK script to your website. Place it before the closing </body> tag or in your <head> with the async attribute:
<script src="https://cdn.getoutrun.com/sdk/outrun.min.js" async></script>
The script loads asynchronously and does not block page rendering. The widget launcher appears in the bottom-right corner of the page once loaded.
Workspace Connection
The SDK automatically connects to your workspace based on the domain configuration in your Outrun settings. No API keys are exposed in client-side code.
Identifying Visitors
By default, chat visitors are anonymous. Use the identify() method to associate the visitor with a known user. This gives your agents access to the visitor's profile, company, and history.
Outrun.identify({
email: "[email protected]",
name: "Jane Smith",
company: "Acme Corp",
plan: "enterprise",
role: "VP Sales"
});
When to Call identify()
- Logged-in users — call
identify()after authentication completes - Known visitors — call after a visitor submits their email in a form or during chat
- Anonymous visitors — skip
identify(). The agent will ask for details during conversation if configured
Available Fields
| Field | Type | Description |
|---|---|---|
email |
string | Visitor's email address (primary identifier) |
name |
string | Display name |
company |
string | Company or organisation name |
plan |
string | Current plan or subscription tier |
role |
string | Job title or role |
Custom fields can be passed as additional key-value pairs. All fields are available to agents via the `` template variable.
Sending Messages Programmatically
Open the chat widget and send a message on behalf of the visitor:
// Open the widget
Outrun.open();
// Send a message
Outrun.sendMessage("I need help with my account");
This is useful for triggering contextual conversations based on user actions (e.g. clicking a "Help" button on a specific feature page).
Widget Configuration
The chat widget inherits its configuration from your agent settings in the Outrun dashboard:
- Agent name and avatar — displayed in the chat header
- Welcome message — shown when the widget opens
- Email capture delay — how long before the agent asks for the visitor's email (configured per-agent)
- HITL mode — whether responses are sent immediately or queued for review
No client-side configuration is required beyond the script tag and optional identify() call.
How Messages Flow
- Visitor types a message in the chat widget
- The SDK sends the message to the Outrun API gateway
- If multiple agents are deployed, the auto-router classifies the message and routes to the right specialist
- The specialist agent generates a response using its prompt, tools, and workspace context
- If HITL is enabled and the response needs review, it queues for human approval
- The response is delivered back to the widget in real time
All messages are stored in your workspace database and visible in the Outrun dashboard.
Content Security Policy
If your website uses a Content Security Policy (CSP), add the following directives:
script-src 'self' https://cdn.getoutrun.com;
connect-src 'self' https://api.outrun.dev;
The SDK loads from cdn.getoutrun.com and communicates with api.outrun.dev. No inline scripts or styles are injected.
Troubleshooting
Widget doesn't appear
- Verify the script tag is present and the URL is correct
- Check the browser console for CSP or network errors
- Confirm you have at least one active chat agent in your workspace
identify() not working
- Call
identify()after the SDK has loaded. If usingasync, wrap in a load handler:
window.addEventListener('outrun:ready', function() {
Outrun.identify({ email: "[email protected]" });
});
- Verify the email field is present — it's the primary identifier
Messages not reaching agents
- Check that your chat agent's workflow is active (status: enabled)
- Verify the agent has a chat channel configured
- Check the workflow run history in the Outrun dashboard for error details
