Chat Widget Interface
Embed your agent as a chat widget in websites and applications
The Chat Widget interface (formerly Embedded Chat) allows you to embed your agent as an interactive chat widget in websites, applications, or other digital platforms. This interface provides seamless integration for your own properties while maintaining full control over the user experience.
Looking for Airia Catalog (platform interface)? See Airia Catalog Interface.
For an overview of managing all interface types, see Managing Agent Interfaces.
Key Features
Seamless Integration
- Custom Embed Code: Easy-to-implement code for web integration
- Responsive Design: Automatically adapts to different screen sizes
- Customizable Appearance: Configure colors, positioning, and behavior
Complete Control
- Your Brand: Maintain your brand identity and user experience
- Placement Control: Choose which pages carry the widget; anyone who can open those pages can chat with the agent
- Independent Operation: Take offline without affecting other interfaces
Before You Start
- Permission to manage agent deployment interfaces in Airia.
- For SharePoint: a SharePoint Administrator to upload the package to the Apps site and add the Airia script sources, and edit rights on the page where the widget goes.
Configuration Steps
Access the interfaces panel by either:
- Clicking the ellipsis (…) menu to the right of your Agent and selecting Interfaces
- Opening the Agent in Studio and clicking Settings > Interfaces
In the interfaces panel:
- Click + Add Interface if this is a new interface
- Select Chat Widget from the available interface types
- Or click the edit icon next to an existing Chat Widget interface to modify its configuration
Click Generate API Key. The Embed Configurator opens with the Pipeline ID, API Key, and API URL for your agent already filled in under Required.
Adjust the widget in the Appearance, Floating Button, Chat Behavior, and Theme Customization sections. The code under Embed Code updates as you change settings.
Click Copy under Embed Code and add the code to your website or application:
- Paste the code into the pages where you want the widget to appear
- Test the integration in a development environment first
- Verify the widget loads and functions correctly
The widget runs your agent's published version. When you publish a new version, the widget uses it without any change to the embed code.
Integration Options
JavaScript Widget
The complete, ready-to-use embed code is provided under Embed Code in the Chat Widget interface. The example below illustrates the structure. Always copy the generated code from your interface for actual integration, since it carries the API URL for your Airia environment.
The widget renders as a floating button fixed to a corner of the page. Selecting the button opens the chat panel above it.
Positioning the floating button: position ("left" or "right", default "right") selects the corner. offsetBottom and offsetSide (both in pixels, default 20, clamped to a 0–200 range) control how far the button sits from the bottom and side edges of the page; offsetSide applies to whichever edge position selects. Increase these values to move the button clear of another fixed element in the same corner (for example, the Microsoft 365 Copilot launcher on SharePoint pages; see SharePoint Chat Widget below). The generated code includes these options only when you change them from their defaults.
The example uses the Airia US cloud host, https://embed-api.airia.ai. Regional instances use https://<region>.embed-api.airia.ai (for example https://eu1.embed-api.airia.ai), and custom or self-managed domains use https://embed-api.<your-domain>. If your generated embed code shows a different host, use that one.
Example structure:
<!-- Airia Chat Embed -->
<script type="module">
import AiriaChat from "https://embed-api.airia.ai/get-chat-embed-v2.js"
AiriaChat.init({
pipelineId: "your-agent-id",
apiKey: "your-api-key",
apiUrl: "https://embed-api.airia.ai",
greeting: "Hello! How can I assist you today?",
position: "left",
offsetBottom: 80
})
</script>SharePoint Chat Widget
Use the SharePoint Chat Widget interface to add the same chat widget to SharePoint pages as a SharePoint Framework web part.
In the agent's interfaces panel, click + Add Interface and select SharePoint Chat Widget. From an existing Chat Widget, you can also click Configure SharePoint Chat Widget.
If the Required Configuration table is blurred, click Generate API Key. The Chat Widget and the SharePoint Chat Widget share one API key per agent, so if you already generated a key for the Chat Widget, the table shows it.
Regenerate API Key replaces the key for both the Chat Widget and the SharePoint Chat Widget. Update every page that uses the old key.
Under SharePoint Package, click Download .sppkg Package.
A SharePoint Administrator opens More features in the SharePoint admin center, selects Open under Apps, and on the Manage apps page selects Upload and chooses the .sppkg file. In the Enable app panel, select Enable this app and add it to all sites to make the web part available on every site, then select Enable app. See Microsoft's Manage apps using the Apps site.
If you don't add it to all sites, a site owner adds the app to their site from the apps listed under From Your Organization.
Complete the Trusted script sources configuration below.
Edit the SharePoint page, click the + where you want to add content, search for Airia Chat, and add it. See Microsoft's Using web parts on SharePoint pages.
Open the web part's properties. Under Airia Configuration, copy each value from the Required Configuration table in Airia:
| Airia property | Web part field |
|---|---|
pipelineId | Pipeline ID |
apiKey | API Key |
apiUrl | API URL |
Replace the web part's default API URL with the value from Airia. Leave the Advanced Options settings at their defaults, with Embed Script URL empty, so the web part loads the chat script from your API URL. If Embed Script URL already has a value, clear it.
The Optional Configuration table in Airia lists the settings you can change in the web part: Greeting Message under Airia Configuration, and Image Path (Icon URL), Image Size, Image Background Color, and Auto Open Chat under Appearance Settings. Use Chat Position to choose the left or right corner. Then publish the page.
The Airia chat button appears in the corner of the page you chose. Select it to open the chat and send a test message.
Avoiding the Microsoft 365 Copilot button: on pages where a user has a Copilot license, the Copilot launcher and the Airia chat button can occupy the same corner. In the web part's properties, under Appearance Settings, use the Offset from Bottom (px) and Offset from Side (px) sliders (0–200px, default 20) to move the Airia button clear of Copilot's button. This requires web part package version 1.1.0 or later.
Trusted Script Sources Configuration
SharePoint enforces Content Security Policy (CSP) restrictions that block external scripts by default. After installing or upgrading the web part package, a SharePoint Administrator must allow the Airia hosts that the web part loads its script from.
In the SharePoint admin center, go to Advanced > Script sources and select Add source. See Microsoft's Support for Content Security Policy (CSP) in SharePoint Online.
Add each of these as a separate source:
- The API URL from the Required Configuration table (for example,
https://embed-api.airia.ai) - The Chat URL from the same table (for example,
https://chat.airia.ai; on a regional instance both hosts carry the region prefix,https://<region>.chat.airia.aiandhttps://<region>.embed-api.airia.ai) https://cdn.airia.ai
SharePoint blocks the widget script until both hosts are in the trusted script sources list. Check this for new installations and for upgrades to newer versions of the web part package.
Who the Widget Runs As
Chat Widget and SharePoint Chat Widget conversations run under the widget's API key, not as the person viewing the page. Airia doesn't receive the visitor's identity, so:
- Data sources that check each user's permissions return only content the widget's API key identity can access, not content restricted to the individual visitor.
- Tools set to use each user's own credentials can't act as the visitor.
For employee-facing agents that should answer with each person's own access, deploy the agent to the Airia Catalog, where people sign in to Airia (through your organization's SSO when it's configured), and link to it from your intranet.
Managing Your Chat Widget
Monitoring Usage
- Conversation Analytics: Track widget interactions and usage patterns
- Performance Metrics: Monitor response times and user satisfaction
- Error Tracking: Identify and resolve integration issues
Customization
- Visual Branding: Update colors, fonts, and styling to match your brand
- Behavior Settings: Configure auto-open, greeting messages, and interaction flows
- Content Updates: Modify prompts, descriptions, and capabilities as needed
Maintenance
- Version Control: The widget automatically uses your agent's published version
- Uptime Management: Take widget offline for maintenance without affecting other interfaces
- Integration Updates: Update embed code when making significant changes
Best Practices
User Experience
- Clear Purpose: Make it obvious what your chat widget can help with
- Helpful Prompts: Provide example questions that demonstrate value
- Quick Responses: Ensure your agent provides timely, relevant responses
- Graceful Fallbacks: Handle edge cases and unexpected inputs well
Technical Implementation
- Test Thoroughly: Verify widget functionality across different browsers and devices
- Performance: Ensure the widget doesn't negatively impact page load times
- Security: Place the widget only on pages whose audience should reach the agent, and keep the API key in the embed code for those pages only
- Monitoring: Set up analytics to track usage and identify issues
Brand Consistency
- Visual Integration: Match your website's design language and color scheme
- Voice and Tone: Ensure your agent's responses align with your brand voice
- Content Quality: Maintain high-quality, brand-appropriate responses