Skip to Content
WidgetWidget Guide

Widget Guide

The Agentix chat widget is an embeddable UI component that adds a conversational AI interface to any website. It loads asynchronously, is fully responsive, and can be customized to match your brand.

Quick Embed

Add this script tag to your HTML, just before the closing </body> tag:

<script
  src="https://cdn.agentix.cl/widget/v1/embed.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="agx_live_YOUR_API_KEY"
></script>

That’s it. The widget will appear as a floating button in the bottom-right corner of your page.

Configuration Options

Pass configuration as data-* attributes on the script tag:

AttributeTypeDefaultDescription
data-agent-idstringRequiredYour agent’s ID
data-api-keystringRequiredYour public API key
data-api-urlstringhttps://app.agentix.clCustom API base URL
data-positionstringbottom-rightWidget position: bottom-right, bottom-left, top-right, top-left
data-languagestringesUI language: es, en
data-themestringlightColor scheme: light, dark
data-auto-openbooleanfalseOpen widget automatically on page load
data-auto-open-delaynumber3000Delay before auto-open (milliseconds)
data-trigger-textstring-Custom text on the trigger button

Example with Options

<script
  src="https://cdn.agentix.cl/widget/v1/embed.js"
  data-agent-id="abc123"
  data-api-key="agx_live_YOUR_KEY"
  data-position="bottom-left"
  data-language="en"
  data-theme="dark"
  data-auto-open="true"
  data-auto-open-delay="5000"
></script>

Manual Initialization

For more control, load the script without auto-init and initialize manually:

<script src="https://cdn.agentix.cl/widget/v1/embed.js" data-manual-init="true"></script>
 
<script>
  // Initialize when ready
  window.AgentixWidget.init({
    agentId: 'YOUR_AGENT_ID',
    apiKey: 'agx_live_YOUR_KEY',
    position: 'bottom-right',
    language: 'en',
    theme: 'light',
    onReady: function() {
      console.log('Widget is ready')
    },
    onMessage: function(message) {
      console.log('New message:', message)
    },
  })
</script>

Widget API

After initialization, the widget exposes a global API:

// Open the widget
window.AgentixWidget.open()
 
// Close the widget
window.AgentixWidget.close()
 
// Toggle open/close
window.AgentixWidget.toggle()
 
// Send a message programmatically
window.AgentixWidget.sendMessage('Hello!')
 
// Destroy the widget and clean up
window.AgentixWidget.destroy()
 
// Set visitor information
window.AgentixWidget.setVisitor({
  email: 'user@example.com',
  name: 'John Doe',
  metadata: { plan: 'pro' }
})

How It Works

  1. The embed script loads asynchronously (does not block page rendering)
  2. It fetches the agent’s widget configuration from /api/public/agents/{id}/widget
  3. It creates an isolated iframe to prevent CSS conflicts with your site
  4. Messages are sent via the Chat API with streaming responses
  5. Conversations persist via sessionId stored in localStorage

Domain Restrictions

For security, you can restrict which domains can load your widget:

  1. Go to your agent’s settings in the dashboard
  2. Under Widget Configuration > Allowed Domains
  3. Add your domains (supports wildcards: *.example.com)

When domain restrictions are active, the widget will only load on approved domains. Requests from other origins receive a 403 DOMAIN_NOT_ALLOWED error.

Content Security Policy (CSP)

If your site uses a strict CSP, add these directives:

script-src 'self' https://cdn.agentix.cl;
frame-src 'self' https://cdn.agentix.cl;
connect-src 'self' https://app.agentix.cl;

Next Steps

Last updated on
WebhooksWidget Customization