Embeddable Agent Widgets

Brightsy AI allows you to embed AI agents directly into your website or application using agent widgets. This provides a seamless way for your users to interact with your AI agents without leaving your platform.

How Agent Widgets Work

Agent widgets are embedded using a JavaScript snippet that loads an interactive chat interface. The widget connects to your Brightsy AI agent using an API key and agent ID, allowing real-time communication with your configured agent.

Generating Embed Code

To generate an embed code for your agent:

1. Navigate to the API Keys section in your Brightsy AI dashboard
2. Create a new API key or select an existing one
3. Click on the embed code icon (</>) next to your API key
4. Copy the generated script tag from the modal dialog

Embedding Your Agent

Add the script tag to your HTML page where you want the agent widget to appear:

<script async defer 
  src="https://brightsy.ai/embed/agent-widget.js" 
  data-agent="your-agent-id" 
  data-apikey="your-api-key">
</script>

The widget will render at the location where you place the script tag, or you can specify a container using the data-container attribute.

Configuration Options

The agent widget script supports several configuration attributes:

Required Attributes:

• data-agent: The ID of the agent you want to embed
• data-apikey: Your API key for authentication

Optional Attributes:

• data-container: ID of a DOM element where the widget should be rendered
• data-cssurl: URL to a custom CSS file for styling the widget

Customizing Appearance

You can customize the appearance of your agent widget in two ways:

1. Using CSS Variables: The widget inherits CSS variables from your page, allowing you to control colors, fonts, and other styling properties
2. Custom CSS File: Provide a URL to your own CSS file using the data-cssurl attribute for complete styling control

Best Practices

Choose Appropriate Permissions
Create dedicated API keys for widgets with only the necessary permissions for your use case.

Consider User Experience
Position the widget where it enhances user experience without disrupting page flow or content.

Implement Proper Error Handling
Add error handling for situations where the agent or API may be unavailable.

Test Across Devices
Ensure your embedded widget works well across different screen sizes and devices.

Monitor Usage
Regularly check your API usage to optimize costs and performance.

Common Use Cases

Embeddable agent widgets are ideal for:

• Customer support chatbots on company websites
• Knowledge base assistants for documentation sites
• Product recommendation engines on e-commerce platforms
• Interactive guides and wizards for complex applications
• Training assistants for educational platforms