Widget customization

Learn how to customize the widget appearance to match your brand, and personalize the agent’s behavior from html.

Widgets enable instant integration of Conversational AI into any website. You can either customize your widget through the UI or through our type-safe Conversational AI SDKs for complete control over styling and behavior. The SDK overrides take priority over UI customization.

Widgets currently require public agents with authentication disabled. Ensure this is disabled in the Advanced tab of your agent settings.

Embedding the widget

Add this code snippet to your website’s <body> section. Place it in your main index.html file for site-wide availability:

Widget embed code
1<elevenlabs-convai agent-id="<replace-with-your-agent-id>"></elevenlabs-convai>
2<script src="https://elevenlabs.io/convai-widget/index.js" async type="text/javascript"></script>

For enhanced security, define allowed domains in your agent’s Allowlist (located in the Security tab). This restricts access to specified hosts only.

Widget attributes

This basic embed code will display the widget with the default configuration defined in the agent’s dashboard. The widget supports various HTML attributes for further customization:

1<elevenlabs-convai
2  agent-id="agent_id"              // Required: Your agent ID
3  signed-url="signed_url"          // Alternative to agent-id
4  server-location="us"             // Optional: "us" or default
5  variant="expanded"               // Optional: Widget display mode
6></elevenlabs-convai>
1<elevenlabs-convai
2  avatar-image-url="https://..." // Optional: Custom avatar image
3  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
4  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
5></elevenlabs-convai>
1<elevenlabs-convai
2  action-text="Need assistance?"         // Optional: CTA button text
3  start-call-text="Begin conversation"   // Optional: Start call button
4  end-call-text="End call"              // Optional: End call button
5  expand-text="Open chat"               // Optional: Expand widget text
6  listening-text="Listening..."         // Optional: Listening state
7  speaking-text="Assistant speaking"     // Optional: Speaking state
8></elevenlabs-convai>

Runtime configuration

Two more html attributes can be used to customize the agent’s behavior at runtime. These two features can be used together, separately, or not at all

Dynamic variables

Dynamic variables allow you to inject runtime values into your agent’s messages, system prompts, and tools.

1<elevenlabs-convai
2  agent-id="your-agent-id"
3  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
4></elevenlabs-convai>

All dynamic variables that the agent requires must be passed in the widget.

See more in our dynamic variables guide.

Overrides

Overrides enable complete customization of your agent’s behavior at runtime:

1<elevenlabs-convai
2  agent-id="your-agent-id"
3  override-config='{
4    "agent": {
5      "prompt": {
6        "prompt": "Custom system prompt for this user"
7      },
8      "first_message": "Hi! How can I help you today?",
9      "language": "es"
10    }
11  }'
12></elevenlabs-convai>

Overrides can be enabled for specific fields, and are entirely optional.

See more in our overrides guide.

Visual customization

Customize the widget’s appearance, text content, language selection, and more in the dashboard Widget tab.

Widget customization

Customize the widget colors and shapes to match your brand identity.

Widget appearance

Advanced implementation

For more advanced customization, you should use the type-safe Conversational AI SDKs with a Next.js, React, or Python application.

Client Tools

Client tools allow you to extend the functionality of the widget by adding event listeners. This enables the widget to perform actions such as:

  • Redirecting the user to a specific page
  • Sending an email to your support team
  • Redirecting the user to an external URL

To see examples of these tools in action, start a call with the agent in the bottom right corner of this page. The source code is available on GitHub for reference.

Creating a Client Tool

To create your first client tool, follow the client tools guide.

Client tool configuration

Example Implementation

Below is an example of how to handle the redirectToExternalURL tool triggered by the widget in your JavaScript code:

index.js
1document.addEventListener('DOMContentLoaded', () => {
2  const widget = document.querySelector('elevenlabs-convai');
3
4  if (widget) {
5    // Listen for the widget's "call" event to trigger client-side tools
6    widget.addEventListener('elevenlabs-convai:call', (event) => {
7      event.detail.config.clientTools = {
8        // Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
9        redirectToExternalURL: ({ url }) => {
10          window.open(url, '_blank', 'noopener,noreferrer');
11        },
12      };
13    });
14  }
15});

Explore our type-safe SDKs for React, Next.js, and Python implementations.

Built with