Embedding Guide

Learn how to embed Agent5ive agents in your websites and applications.

Overview

Agent5ive provides multiple ways to embed your agents into your own websites and applications. This allows your users to interact with your agents directly from your digital properties without having to visit the Agent5ive platform.

There are two primary methods for embedding your agents:

JavaScript SDK - A lightweight script that adds a chat widget to your website
iFrame Embedding - Directly embed the agent chat interface into your webpage

Important: Before you can embed an agent, it must be published publicly in your Agent5ive dashboard. Private agents cannot be embedded or accessed through the JavaScript SDK or iFrame embedding.

Important: Agent Visibility Setting

Agents must be published publicly in your Agent5ive dashboard for embedding to work. Private agents cannot be accessed through the JavaScript SDK or iFrame embedding.

To publish your agent publicly, go to your Agent5ive dashboard, select the agent, navigate to the "Deploy" tab, and click the "Publish Publicly" button.

JavaScript SDK

The JavaScript SDK is the easiest way to add your agent to any website. It creates a customizable chat widget that appears as a button in the corner of your site. When clicked, it opens a chat interface where users can interact with your agent.

Installation

To add the Agent5ive chat widget to your website, add the following script tag to the <body> section of your HTML:

<script src="https://agent5ive.com/agent5ive.js" defer></script>

Then, initialize the widget with your agent's deployment ID and configuration options:

<script>
  document.addEventListener('DOMContentLoaded', function() {
    if (window.AgentXChat && window.AgentXChat.init) {
      window.AgentXChat.init({
        deploymentId: "YOUR_DEPLOYMENT_ID",
        agentName: "Your Agent Name",
        baseUrl: "https://agent5ive.com",
        buttonText: "Chat with Agent",
        buttonColor: "#0ea5e9",
        buttonTextColor: "#ffffff",
        chatWindowColor: "#ffffff",
        chatWindowTextColor: "#000000",
        headerColor: "#0ea5e9",
        headerTextColor: "#ffffff",
        position: "right",
        bottomOffset: "20px",
        rightOffset: "20px",
        zIndex: 1000,
        initialMessage: "Hi there! How can I help you today?"
      });
    }
  });
</script>

What Users Will See

When you embed your agent using the JavaScript SDK, users will see:

Chat Button - A floating button in the corner of your website with your agent's name
Chat Interface - When clicked, a chat window opens with your agent's welcome message
Tool Indicators - If you've enabled tools like Web Browsing or Trend Search, users will see toggles for these tools
Voice Chat Option - If you've enabled voice features, users will see a microphone button
Image Upload - If you've enabled image vision, users will see an upload button

The chat interface is designed to be intuitive and user-friendly, with your agent's personality and capabilities fully preserved.

User Experience:

When a user interacts with your embedded agent, they'll experience the same high-quality conversations as on the Agent5ive platform. Your agent will maintain its personality, use its configured tools appropriately, and provide the specialized assistance you designed it for.

Voice-Enabled Agents Require Microphone Permissions

If your agent uses voice features, users will be prompted to grant microphone access when they interact with the voice functionality. Make sure to inform your users about this requirement. The JavaScript SDK automatically handles the permission requests when needed.

Configuration Options

Option	Type	Required	Description
deploymentId	string	Yes	The unique ID of your agent deployment (found in your Agent5ive dashboard)
agentName	string	Yes	The name of your agent (displayed in the chat header)
baseUrl	string	Yes	The base URL of the Agent5ive platform
buttonText	string	Yes	The text displayed on the chat button
buttonColor	string	No	The background color of the chat button (hex code)
buttonTextColor	string	No	The text color of the chat button (hex code)
chatWindowColor	string	No	The background color of the chat window (hex code)
chatWindowTextColor	string	No	The text color of the chat window (hex code)
headerColor	string	No	The background color of the chat header (hex code)
headerTextColor	string	No	The text color of the chat header (hex code)
mobileBreakpoint	number	No	The screen width (in pixels) at which to switch to mobile view
mobileFullScreen	boolean	No	Whether to display the chat in full screen on mobile devices
position	string	No	The position of the chat button ('left' or 'right')
bottomOffset	string	No	The distance from the bottom of the screen (CSS value)
rightOffset	string	No	The distance from the right of the screen (CSS value)
zIndex	number	No	The z-index of the chat widget (for layering with other elements)
initialMessage	string	No	The first message displayed from the agent when the chat is opened

JavaScript API

The Agent5ive JavaScript SDK provides additional methods for programmatically controlling the chat widget:

Method	Description
AgentXChat.open()	Opens the chat window
AgentXChat.close()	Closes the chat window
AgentXChat.toggle()	Toggles the chat window open/closed
AgentXChat.sendMessage(text)	Programmatically sends a message as the user
AgentXChat.clearConversation()	Clears the current conversation history

Example Usage

Here's an example of how to use the JavaScript API to control the chat widget:

<button onclick="window.AgentXChat.open()">Open Chat</button>
<button onclick="window.AgentXChat.close()">Close Chat</button>
<button onclick="window.AgentXChat.toggle()">Toggle Chat</button>
<button onclick="window.AgentXChat.sendMessage('Hello, agent!')">Send Message</button>
<button onclick="window.AgentXChat.clearConversation()">Clear Chat</button>

Custom Styling

You can further customize the appearance of the chat widget by adding CSS variables to your website:

:root {
  --agent5ive-primary-color: #0ea5e9;
  --agent5ive-text-color: #ffffff;
  --agent5ive-bg-color: #ffffff;
  --agent5ive-input-bg-color: #f1f5f9;
  --agent5ive-border-radius: 8px;
  --agent5ive-font-family: 'Inter', sans-serif;
}

Finding Your Deployment ID

To find your agent's deployment ID, go to your Agent5ive dashboard, select the agent you want to embed, click on the "Deploy" tab, and copy the deployment ID from the "Embed" section.

Best Practices

Performance Considerations

Load the JavaScript SDK asynchronously to prevent blocking page rendering
Consider lazy-loading the chat widget only when needed
For iFrames, use a reasonable height to avoid excessive scrolling
Test your embedded agent on various devices and screen sizes

User Experience Tips

Set a clear initial message to guide users on how to interact with the agent
Match the chat widget's colors to your website's branding
Consider using the JavaScript SDK for a less intrusive experience
Use iFrames when you want the chat to be a central part of your page

Security Considerations

When embedding agents in your website, keep these security considerations in mind:

Content Security Policy (CSP) - If your website uses a strict CSP, you may need to addhttps://agent5ive.com to your allowed sources for scripts, frames, and connect-src
User Authentication - Consider using the userId parameter to maintain conversation context for authenticated users
Sensitive Information - Be mindful of what information your agent has access to and what it might share in conversations
Rate Limiting - The Agent5ive platform includes rate limiting to prevent abuse, but you may want to implement additional measures on your side

Getting Help

If you encounter any issues with embedding your agents, or have questions about customization options, please contact our support team at sales@agent5ive.com.

Explore Tool Integration

Documentation

Guides

Tutorials

Help