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

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:

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

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:

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

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

Eager Loading

Fetch messages immediately on mount using fetchOnMount:

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

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:

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:

<Intercom username="customer_support" />

Sales Chat:

<Intercom username="sales_bot" />

Technical Help:

<Intercom username="tech_support" />

Onboarding Assistant:

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

Next Steps

Related Documentation:

PreviousCustomizationNextProps Reference

Last updated