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

Core Concepts:

PreviousIntercomNextMessage Handling

Last updated