Configuration - AmpUp Documentation

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;
}

​Props

​Types

​Examples

​With dynamic variables

​With message logging

​With call state tracking

​Custom agent branding

​Custom client tools

​Hash router support

​Built-in Client Tools

​navigateToPage

​scrollToSection

​Styling

Props

Types

Examples

With dynamic variables

With message logging

With call state tracking

Custom agent branding

Custom client tools

Hash router support

Built-in Client Tools

`navigateToPage`

`scrollToSection`

Styling