---
title: "Chat Widget Interface"
description: "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.

<Note>
Looking for Airia Catalog (platform interface)? See [Airia Catalog Interface](/building-and-deploying-agents/interface-options/airia-agent).

For an overview of managing all interface types, see [Managing Agent Interfaces](/building-and-deploying-agents/interface-options/managing-interfaces).
</Note>

## 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
- **Access Control**: Determine exactly who can access your chat widget
- **Independent Operation**: Take offline without affecting other interfaces

## Configuration Steps

<Steps>
  <Step title="Access the Interfaces Panel" stepNumber={1}>
    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**
  </Step>
  
  <Step title="Add Chat Widget Interface" stepNumber={2}>
    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
  </Step>
  
  <Step title="Generate Embed Code" stepNumber={4}>
    - Click "Generate API Key" to generate a security key specific to this chat widget
  </Step>
  
  <Step title="Implement in Your Website" stepNumber={5}>
    Add the embed code to your website or application:
    - Paste the code into your HTML where you want the widget to appear
    - Test the integration in a development environment first
    - Verify the widget loads and functions correctly
    
    <Info>
    The widget will automatically connect to your agent's Active version and be ready for user interactions.
    </Info>
  </Step>
</Steps>

## Integration Options

### JavaScript Widget

<Note>
The complete, ready-to-use embed code is provided in the Chat Widget interface configuration panel. The example below illustrates the structure and available options—always use the generated code from your interface for actual integration.
</Note>

Example structure:
```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Airia Embed</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module">
      import AiriaChat from "https://{your-environment}.airia.com/get-chat-embed.js"
      AiriaChat.init({pipelineId: "your-pipeline-id",
              apiKey: "your-api-key",
              apiUrl: "https://{your-environment}.embed-api.airia.com",
              greeting: "Hello! How can I assist you today?",
              imagePath: "https://yoursite.com/assets/chatbot-icon.png",
              imageSize: "small",
              imageBgColor: "#FFFFFF",
              autoOpen: true})
    </script>
  </body>
</html>
```

### SharePoint WebPart
Deploying chat widgets on SharePoint requires a specialized packaging of the chat widget into a SharePoint WebPart that can be installed and deployed by your SharePoint administrators.

Reach out to your Airia representative or support@airia.com to obtain the WebPart package (`.sppkg` file).

#### Trusted Script Sources Configuration

SharePoint enforces Content Security Policy (CSP) restrictions that block external scripts by default. After installing or upgrading the WebPart package, a SharePoint administrator must explicitly allow the Airia domains that the WebPart loads scripts from.

<Steps>
  <Step title="Open SharePoint Admin Center">
    Navigate to **SharePoint Admin Center → Settings → Advanced → Trusted script sources**.
  </Step>
  <Step title="Add Airia Domains">
    Add the following domains (substituting the values for your Airia environment):

    - `https://{your-environment}.chat.airia.ai`
    - `https://{your-environment}.embed-api.airia.ai`
  </Step>
</Steps>

<Warning>
The WebPart will not load correctly until both domains are added to the trusted script sources allowlist. This step is required for both new installations and upgrades to newer versions of the WebPart package.
</Warning>

## 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**: Widget automatically uses your agent's Active 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**: Implement appropriate access controls and domain restrictions
- **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

## Troubleshooting

<AccordionGroup>
<Accordion title="How do I ensure my Chat Widget uses the correct agent version?">
All interfaces execute against the **Active version** of your agent. To ensure your Chat Widget uses the latest version:

1. Navigate to your agent in the agent list
2. Verify the Agent shows the correct **Active Version**
3. If an update is required:
   - Go into the Agent
   - Select the version number in the top left
   - Click **Set Active**
   - Return to the agent list

Your Chat Widget will automatically use the updated Active version without requiring code changes.
</Accordion>

<Accordion title="My chat widget isn't loading on my website. What should I check?">
Common integration issues and solutions:

- **Embed Code**: Verify you're using the correct, up-to-date embed code
- **Widget Status**: Ensure the interface is **online** (not taken offline)
- **Domain Restrictions**: Check if domain restrictions allow your website
- **JavaScript Errors**: Look for console errors that might prevent loading
- **Content Security Policy**: Ensure your CSP allows the widget domain
- **HTTPS**: Verify both your site and the widget use HTTPS

Use browser developer tools to inspect network requests and console errors.
</Accordion>

<Accordion title="How do I customize the appearance of my chat widget?">
Customize your Chat Widget appearance through:

1. **Interface Configuration**: Use the visual settings in the interface configuration panel
2. **JavaScript Options**: Use configuration parameters in the JavaScript integration
3. **Brand Colors**: Set primary and accent colors to match your brand

Changes to appearance settings take effect immediately for new widget loads.
</Accordion>

<Accordion title="Can I have multiple chat widgets for the same agent?">
Currently, each agent supports one Chat Widget interface configuration. However, you can:

- **Multiple Agents**: Create different agents with different Chat Widget configurations
- **Configuration Updates**: Modify the single Chat Widget configuration as needed
- **Other Interface Types**: Use additional interface types (Airia Catalog, API) simultaneously

If you need multiple widget configurations, consider creating specialized agents for different use cases.
</Accordion>
</AccordionGroup>