> 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/props-reference.md).

# Props Reference

Complete API reference for the `Intercom` component props.

***

## Props

### username

The deva's username to chat with.

**Type:** `string`

**Required:** Yes

**Example:**

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

**Details:**

* Must match an existing deva username on the Deva platform
* Case-sensitive
* Can be found in deva profile URL: `deva.me/@{username}`
* If invalid, shows "Deva Not Found" error

***

### fetchOnMount

Whether to fetch messages immediately when component mounts.

**Type:** `boolean`

**Required:** No

**Default:** `false`

**Example:**

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

**Details:**

* `false` (default): Messages only fetched when user opens chat
* `true`: Messages fetched immediately on component mount
* Useful for pre-loading conversations
* Increases initial data usage when enabled

***

## Usage Examples

### Basic Usage

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

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

### With Eager Loading

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

### Dynamic Username

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

function App() {
  const [devaUsername, setDevaUsername] = useState("support");

  return (
    <div>
      <button onClick={() => setDevaUsername("sales")}>
        Switch to Sales
      </button>
      <Intercom username={devaUsername} />
    </div>
  );
}
```

### Conditional Rendering

```tsx
function App() {
  const [showSupport, setShowSupport] = useState(false);

  return (
    <div>
      <button onClick={() => setShowSupport(true)}>
        Get Support
      </button>

      {showSupport && <Intercom username="support" />}
    </div>
  );
}
```

***

## Props Behavior

### username Prop

**Valid Username:**

```tsx
<Intercom username="existing_deva" />
// Opens chat successfully
```

**Invalid Username:**

```tsx
<Intercom username="nonexistent_deva" />
// Shows "Deva Not Found" error
```

**Dynamic Changes:**

```tsx
// Changing username creates a new thread
const [username, setUsername] = useState("support");

<Intercom username={username} />
// When username changes, component resets and loads new deva
```

***

### fetchOnMount Prop

**Default Behavior (false):**

```tsx
<Intercom username="support" />
// Messages NOT fetched until user opens chat
// Lower initial load time
// Better for most use cases
```

**Eager Loading (true):**

```tsx
<Intercom username="support" fetchOnMount={true} />
// Messages fetched immediately on mount
// Chat opens faster when clicked
// Higher initial load time
```

**Use Cases for fetchOnMount={true}:**

* Pre-loading important conversations
* Checking for unread messages on page load
* Background syncing for active support sessions
* Reducing perceived latency when chat is frequently used

***

## Component States

### Authentication States

**Unauthenticated:**

```tsx
<Intercom username="support" />
// Component returns null (nothing rendered)
// User must log in first
```

**Authenticated:**

```tsx
<Intercom username="support" />
// Floating button appears in bottom-right
// Ready to open chat
```

### Loading States

**Initial Mount:**

1. Component renders
2. Checks authentication
3. If fetchOnMount={true}, loads deva + messages
4. If fetchOnMount={false}, waits for user to open

**Opening Chat:**

1. User clicks floating button
2. Loads deva persona info
3. Creates/fetches thread
4. Loads message history
5. Displays chat interface

### Error States

**Deva Not Found:**

```tsx
<Intercom username="invalid_username" />
// Shows error screen in popover
// Prevents message sending
// Displays helpful error message
```

**Network Error:**

* Shows error message
* Allows retry
* Maintains component state

***

## TypeScript Interface

```typescript
interface IntercomProps {
  username: string;
  fetchOnMount?: boolean;
}
```

***

## Internal Implementation

The component internally:

* Uses `useDevaPersona` hook to fetch deva information
* Uses `useDevaThread` hook to manage conversation thread
* Uses `useDevaMessages` hook for message fetching and pagination
* Implements Portal for positioning
* Uses Popover for modal behavior
* Manages open/closed state internally

**Data Flow:**

1. Receives `username` prop
2. Fetches deva persona by username
3. Creates/fetches DM thread with deva
4. Loads messages (if fetchOnMount or when opened)
5. Renders floating button + chat interface

***

## Performance Considerations

**Single Instance:**

```tsx
<Intercom username="support" />
// Optimal performance
```

**Multiple Instances:**

```tsx
<Intercom username="support" />
<Intercom username="sales" />
// Each instance maintains separate state
// Higher memory usage
// Consider conditional rendering instead
```

**Recommended Pattern:**

```tsx
function App() {
  const [activeChat, setActiveChat] = useState<string | null>(null);

  return (
    <>
      <button onClick={() => setActiveChat("support")}>Support</button>
      <button onClick={() => setActiveChat("sales")}>Sales</button>

      {activeChat && <Intercom username={activeChat} />}
    </>
  );
}
```

***

## Best Practices

**Username Validation:**

* Verify username exists before deploying to production
* Handle "Deva Not Found" error gracefully
* Don't frequently change username prop (causes re-initialization)

**fetchOnMount Usage:**

* Default to `false` for better initial load performance
* Use `true` only when pre-loading is beneficial
* Consider user experience trade-offs

**Placement:**

* Render once at app root level
* Don't place inside scrollable containers
* Let component handle positioning automatically

***

## Related Documentation

* [Basic Usage](/components/basic-usage-1.md) - How to use Intercom
* [Message Handling](/components/basic-usage-1/message-handling.md) - Understanding messages
* [Customization](/components/basic-usage-1/customization.md) - Styling options
* [Components Overview](/components/overview.md) - Other components

**Core Concepts:**

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