Configuration

Props, types, and customization options for the AmpUp Chat Widget

Props

Prop	Type	Default	Description
agentId	string	(required)	Your ElevenLabs Conversational AI agent ID
position	"bottom-right" | "bottom-left"	"bottom-right"	Widget position on the page
defaultOpen	boolean	false	Start with the chat panel open
agentName	string	"Agent"	Display name shown in the widget header and agent card
agentImageUrl	string | null	null	Custom avatar image URL. If not set, the widget auto-fetches the avatar from your ElevenLabs agent config
dynamicVariables	Record<string, any>	undefined	Key-value pairs passed to the ElevenLabs agent as dynamic variables (e.g. current user info, page context)
clientTools	Record<string, Function>	undefined	Custom client tools the agent can invoke. Merged with built-in tools (navigateToPage, scrollToSection)
routerType	"browser" | "hash" | "auto"	"auto"	Router type used by your app. Controls how built-in navigation tools work
className	string	undefined	Additional CSS class on the root container
onCallStateChange	(state: CallUIState) => void	undefined	Callback when the call/chat state changes
onChatMessage	(message: ChatMessage) => void	undefined	Callback fired on every message (user or agent)

Types

The package exports these TypeScript types:

interface ChatMessage {
  id: string;
  text: string;
  sender: "user" | "agent";
}

type CallUIState = "idle" | "connecting" | "in-call" | "in-chat";

interface ChatWidgetProps {
  agentId: string;
  position?: "bottom-right" | "bottom-left";
  dynamicVariables?: Record<string, any>;
  agentName?: string;
  agentImageUrl?: string | null;
  clientTools?: Record<string, (parameters: any) => Promise<string | undefined>>;
  className?: string;
  defaultOpen?: boolean;
  routerType?: "browser" | "hash" | "auto";
  onCallStateChange?: (state: CallUIState) => void;
  onChatMessage?: (message: ChatMessage) => void;
}

Examples

With dynamic variables

Pass context to your agent using dynamicVariables. These are sent to the ElevenLabs agent when a session starts:

import { ChatWidget } from "@ampup/chat-widget";

function App() {
  return (
    <ChatWidget
      agentId="agent_xxxxx"
      dynamicVariables={{
        userName: "Jane",
        currentPage: window.location.pathname,
        plan: "enterprise",
      }}
    />
  );
}

With message logging

Track every message exchanged between the user and agent:

<ChatWidget
  agentId="agent_xxxxx"
  onChatMessage={(msg) => {
    console.log(`[${msg.sender}] ${msg.text}`);
    // Send to your analytics service
  }}
/>

With call state tracking

Monitor the widget’s connection state:

<ChatWidget
  agentId="agent_xxxxx"
  onCallStateChange={(state) => {
    // state: "idle" | "connecting" | "in-call" | "in-chat"
    console.log("Widget state:", state);
  }}
/>

Custom agent branding

<ChatWidget
  agentId="agent_xxxxx"
  agentName="Support Bot"
  agentImageUrl="https://example.com/avatar.png"
  position="bottom-left"
  defaultOpen
/>

If you don’t provide agentImageUrl, the widget automatically fetches the avatar from your ElevenLabs agent configuration.

Custom client tools

Register tools that the ElevenLabs agent can invoke during a conversation. These are merged with the built-in navigateToPage and scrollToSection tools:

<ChatWidget
  agentId="agent_xxxxx"
  clientTools={{
    openPricingModal: async (params) => {
      document.getElementById("pricing-modal")?.classList.add("open");
      return "Opened pricing modal";
    },
    getCurrentCart: async () => {
      const items = getCartItems();
      return JSON.stringify(items);
    },
  }}
/>

Each tool function receives the parameters the agent passes and should return a string response (or undefined).

Hash router support

If your app uses a hash-based router (e.g. HashRouter from React Router), set routerType so the built-in navigation tools work correctly:

<ChatWidget
  agentId="agent_xxxxx"
  routerType="hash"
/>

Value	Behavior
"auto"	Auto-detects based on whether the current URL hash looks like a route (e.g. /#/about)
"browser"	Uses history.pushState for navigation (standard HTML5 routing)
"hash"	Uses window.location.hash for navigation

Built-in Client Tools

The widget registers two client tools that your ElevenLabs agent can call:

navigateToPage

Navigates the user to a different page within your app. Works with both browser and hash routers.

Agent calls: navigateToPage({ page: "/pricing" })
→ Widget navigates the SPA to /pricing

scrollToSection

Scrolls to and highlights a specific section on the page using a spotlight effect.

Agent calls: scrollToSection({ section: "features" })
→ Widget scrolls to #features and applies a temporary golden highlight

For scrollToSection to work, your page sections need id attributes (e.g. <section id="features">).

Styling

The widget renders all UI with inline styles and injects its own CSS animations. No external stylesheet import is required.

The component accepts a className prop if you need to target it for layout purposes:

<ChatWidget agentId="agent_xxxxx" className="my-chat-widget" />

The widget uses a dark theme (#0d0d1a background) with an indigo/purple accent (#6366f1 to #7c3aed). To customize the appearance, you can override styles by targeting the widget’s fixed-position container:

/* Example: adjust z-index */
.my-chat-widget {
  z-index: 99999 !important;
}