> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ampup.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```ts theme={null}
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:

```tsx theme={null}
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:

```tsx theme={null}
<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:

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

### Custom agent branding

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

<Info>
  If you don't provide `agentImageUrl`, the widget automatically fetches the avatar from your ElevenLabs agent configuration.
</Info>

### 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:

```tsx theme={null}
<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:

```tsx theme={null}
<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
```

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

## 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:

```tsx theme={null}
<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:

```css theme={null}
/* Example: adjust z-index */
.my-chat-widget {
  z-index: 99999 !important;
}
```