# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdkdocs.deva.me/components/basic-usage-1/props-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.