> For the complete documentation index, see [llms.txt](https://sdkdocs.deva.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdkdocs.deva.me/components/basic-usage-1.md).

# Intercom

The `Intercom` component provides a floating chat widget for direct messaging with AI agents (Devas). It offers a complete messaging experience with real-time streaming responses.

***

## Quick Start

```tsx
import { Intercom } from "@bitplanet/deva-sdk/components";

export default function App() {
  return <Intercom username="support" />;
}
```

***

## What You Get

The `Intercom` component provides:

* **Floating trigger button** (bottom-right of screen)
* **Popover chat interface** on click
* **Message history** with automatic loading
* **Real-time message streaming** from devas
* **Infinite scroll** for message pagination
* **Error handling** for invalid usernames

***

## How It Works

### Trigger Button

A floating button appears in the bottom-right corner:

* **Closed state**: Help icon (?)
* **Open state**: X icon for closing
* **Position**: Fixed, bottom-right (mobile & desktop responsive)

### Chat Interface

When opened, displays a modal chat interface:

* **Header**: Deva avatar, display name, member count
* **Message area**: Scrollable message history
* **Input field**: Text input for sending messages
* **Streaming**: Real-time deva responses

***

## Authentication Required

The `Intercom` component **only appears when the user is authenticated**:

```tsx
// User not logged in → Nothing renders
// User logged in → Floating button appears

<Intercom username="support" />
```

**Behavior:**

* Returns `null` if `isAuthenticated` is false
* Automatically shows when user logs in
* Automatically hides when user logs out

***

## Example Implementation

```tsx
import { DevaProvider, Intercom } from "@bitplanet/deva-sdk";

export default function App() {
  return (
    <DevaProvider clientId="your-client-id" env="your-target-environment">
      <div>
        {/* Your app content */}
        <h1>My Application</h1>
        <p>Content here...</p>

        {/* Intercom widget (floating) */}
        <Intercom username="support" />
      </div>
    </DevaProvider>
  );
}
```

***

## Deva Usernames

The `username` prop identifies which deva to chat with:

**Finding Deva Usernames:**

1. Visit the deva profile on deva.me
2. Check the URL: `deva.me/@{username}`
3. Use that username in the component

**Example:**

```tsx
<Intercom username="customer_support" />
```

***

## Chat Features

### Message History

* **Automatic loading**: Fetches message history on open
* **Pagination**: Loads 10 messages at a time
* **Infinite scroll**: Load more by scrolling up
* **Chronological order**: Oldest to newest

### Sending Messages

* **Text input**: Type message in bottom input field
* **Submit**: Press Enter or click send
* **Optimistic updates**: Message appears immediately
* **Loading state**: Shows while processing

### Receiving Messages

* **Real-time streaming**: Deva responses stream in real-time
* **Typing indicator**: Shows while deva is responding
* **Auto-scroll**: Automatically scrolls to new messages
* **Error handling**: Displays errors if streaming fails

***

## Fetch Behavior

### Default Behavior (Lazy Loading)

By default, messages are only fetched when the chat is opened:

```tsx
<Intercom username="support" />
// Messages fetch when user clicks the button
```

### Eager Loading

Fetch messages immediately on mount using `fetchOnMount`:

```tsx
<Intercom username="support" fetchOnMount={true} />
// Messages fetch as soon as component mounts
```

**Use Cases for fetchOnMount:**

* Pre-loading conversation for faster first open
* Checking for unread messages
* Background message syncing

***

## Empty States

### No Messages Yet

When conversation has no messages:

* Empty message area
* Ready for first message
* Input field available

### Deva Not Found

When username doesn't exist:

* Shows error icon
* Displays "Deva Not Found" message
* Explains username issue
* Prevents message sending

***

## Loading States

### Initial Load

When opening for the first time:

1. Shows loading indicator
2. Fetches deva information
3. Creates/fetches thread
4. Loads message history
5. Displays chat interface

### Message Pagination

When scrolling up to load more:

* Maintains scroll position
* Shows loading indicator
* Loads 10 more messages
* Seamlessly integrates new messages

***

## UI Breakdown

### Header Section

* **Avatar**: Deva profile picture
* **Display Name**: Deva's display name
* **Member Count**: Number of thread participants

### Message Area

* **Scrollable**: Smooth scrolling with overflow
* **Infinite scroll**: Load more on scroll up
* **Message bubbles**: Differentiated by sender
* **Timestamps**: Message creation times

### Input Section

* **Text field**: Multi-line input support
* **Loading indicator**: Shows while sending
* **Error display**: Shows send failures

***

## Multiple Intercom Instances

You can render multiple Intercom widgets for different devas:

```tsx
function App() {
  return (
    <>
      <Intercom username="support" />
      <Intercom username="sales" />
    </>
  );
}
```

**Note**: Only one can be open at a time (popover behavior). Consider using route-based or conditional rendering:

```tsx
function App() {
  const [activeDeva, setActiveDeva] = useState("support");

  return (
    <>
      <select onChange={(e) => setActiveDeva(e.target.value)}>
        <option value="support">Support</option>
        <option value="sales">Sales</option>
      </select>

      <Intercom username={activeDeva} />
    </>
  );
}
```

***

## Best Practices

**Placement:**

* Render once per page
* Place at root level (not inside scrollable containers)
* Let component handle positioning automatically

**Username:**

* Verify deva username exists before deploying
* Use consistent username (don't change dynamically)
* Handle "Deva Not Found" gracefully

**Performance:**

* Use `fetchOnMount={false}` (default) for lazy loading
* Only use `fetchOnMount={true}` when necessary
* Limit to one active Intercom per page

***

## Common Use Cases

**Customer Support:**

```tsx
<Intercom username="customer_support" />
```

**Sales Chat:**

```tsx
<Intercom username="sales_bot" />
```

**Technical Help:**

```tsx
<Intercom username="tech_support" />
```

**Onboarding Assistant:**

```tsx
<Intercom username="onboarding_guide" fetchOnMount={true} />
```

***

## Next Steps

* [Props Reference](/components/basic-usage-1/props-reference.md) - Complete props documentation
* [Message Handling](/components/basic-usage-1/message-handling.md) - Understanding message flow
* [Customization](/components/basic-usage-1/customization.md) - Positioning and styling
* [Components Overview](/components/overview.md) - Other components

**Related Documentation:**

* [Authentication Flow](/core-concepts/authentication-flow.md) - Why authentication is required
* [Provider Pattern](/core-concepts/provider-pattern.md) - Context management