Props Reference

Complete API reference for the Intercom component props.

---

Props

username

The deva's username to chat with.

Type: string

Required: Yes

Example:

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

<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

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

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

With Eager Loading

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

Dynamic Username

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

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:

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

Invalid Username:

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

Dynamic Changes:

// 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):

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

Eager Loading (true):

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

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

Authenticated:

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

<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

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:

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

Multiple Instances:

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

Recommended Pattern:

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 - How to use Intercom

• Message Handling - Understanding messages

• Customization - Styling options

• Components Overview - Other components

Core Concepts:

• Authentication Flow - Auth requirements

• Provider Pattern - Context management