DOCSEARCHbyAlgolia
Submit Docs

EmbeddedChat

repository·develop·Indexed 41 days ago

https://github.com/rocketchat/embeddedchat

A full-stack React-based component library for embedding Rocket.Chat functionality into external web applications. Version 1.0.0 includes a modular architecture for UI components, API interaction, and authentication, featuring a pluggable AI adapter layer for providers like OpenAI, Google Gemini, and Ollama.

Tokens
35.8K
Snippets
130
Records
165
Agent score
51%

What's inside EmbeddedChat

  1. Overview of EmbeddedChat

    develop

    EmbeddedChat is a full-stack React component designed to integrate Rocket.Chat into your web application. It provides a complete UI and backend behavior set, allowing for a seamless chat experience within your existing app.

    Key features include:

    • Full-stack integration: Combines React.js frontend components with backend behaviors.
    • Configurability: Highly flexible with various preconfigured designs and multiple login options.
    • Rocket.Chat Integration: Tightly integrated with the Rocket.Chat server via the Rocket.Chat SDK.
    • Custom UI: The entire user interface is built using custom components.

  2. Overview of EmbeddedChat capabilities

    develop

    EmbeddedChat is a React-based in-app chat solution designed to integrate RocketChat into web applications. It provides a ready-to-go, easy-to-embed mini-chat component with the following core capabilities:

    • Real-time Chat: Powered by the RocketChat node.js SDK.
    • Authentication: Supports RocketChat's Google SSO and standard <username, password> login.
    • UI/UX: Built using the RocketChat Fuselage design system and includes an EmojiOne Emoji Picker for cross-platform emoji support.
    • Message Interactions: Supports pinning, starring, reacting to messages, and mentioning users.
    • REST API Integration: Uses Rocket.Chat's REST API to manage channel details, pinned/starred messages, attachments, and message history.

  3. EmbeddedChat Feature Overview and Capabilities

    develop

    Based on recent development milestones, EmbeddedChat supports several advanced customization and security features:

    • UI Customization: Includes prebuilt themes, style variants (such as Curved Bubble variants), and options for Popup/Sidebar layouts and Username colors.
    • Remote Configuration: Supports Remote EmbeddedChat Settings Configuration, allowing for settings to be managed externally.
    • Security: Enhanced authentication using HTTP-Only cookies.
    • Layout Management: Includes a Real-Time Layout Editor with drag-and-drop capabilities.
    • Modular Architecture: The UI components are managed in a separate component monorepo (@embeddedchat/ui-elements) to improve maintainability and reduce package size.

  4. Overview of EmbeddedChat Monorepo Packages

    develop

    The EmbeddedChat project is organized as a monorepo containing several specialized packages:

    • @embeddedchat/auth: Functions for logging into a RocketChat server. Can be used independently of the main client.
    • @embeddedchat/api: Core logic for creating chat applications. Includes methods for messaging, authentication, and real-time event listeners.
    • @embeddedchat/react: React components for integrating the chat UI into web applications.
    • @embeddedchat/react-native: Support for using EmbeddedChat in React Native mobile applications.
    • @embeddedchat/htmlembed: Enables integration via simple HTML snippets for any web app.

  5. What is the EmbeddedChat RC App?

    develop

    The EmbeddedChat RC App is a full-stack component (React.js + backend) designed to enhance EmbeddedChat functionalities. It provides several key capabilities for embedding Rocket.Chat into web applications:

    • Remote Configuration: Facilitates remote management of EmbeddedChat settings.
    • Secure Authentication: Implements secure login by storing the resume token as an HTTP-only cookie.
    • OAuth Integration: Helps integrate Rocket.Chat OAuth login capabilities.

  6. Customize components with `useComponentOverrides`

    develop

    The useComponentOverrides hook is the primary mechanism for customizing Embedded Chat components. It allows you to inject custom styles, class names, configuration settings, and visual variants into a component.

    Depending on how the hook is used within a component, it returns different sets of overrides:

    1. Style and Class Overrides: Returns styleOverrides (for inline styles) and classNames (for CSS classes).
    2. Config Overrides: Returns configOverrides, which can be used to override component-specific configuration objects (e.g., optionConfig).
    3. Variant Overrides: Returns variantOverrides, which can be used to change the visual state or 'variant' of a component (e.g., changing a display mode from 'Normal' to 'colorize').
    // Basic usage pattern for style and class customization
const { styleOverrides, classNames } = useComponentOverrides(
  "ComponentName",
  className,
  style
);

  7. Understand the package dependency workflow

    develop

    The project uses a monorepo structure where packages have specific dependencies. When making changes to a lower-level package, you must rebuild it before the changes propagate to the packages that depend on it.

    Dependency Chain

    react $\rightarrow$ api $\rightarrow$ auth

    Rebuilding Workflow

    • If you change auth: You must rebuild auth using yarn build inside packages/auth, then restart the api development environment.
    • If you change api: You must rebuild api using yarn build inside packages/api, then restart the react project (Storybook).

  8. EmbeddedChat Monorepo Architecture

    develop

    The project is structured as a monorepo with three core packages that work together to provide the full-stack experience:

    1. react package: The frontend layer. It contains all UI elements, views, and components. It consumes the api and auth packages to communicate with the Rocket.Chat server.
    2. api package: The communication layer. It manages the logic for API calls to the Rocket.Chat backend.
    3. auth package: The identity layer. It manages authentication flows and credentials.

    This separation allows for independent development and testing of the UI, the communication logic, and the authentication mechanisms.

  9. Customize the Matrix Theme and Layout

    develop

    The Matrix integration provides specific visual modes to mimic the Element client experience:

    Matrix Theme Visuals

    Using theme="matrix" applies an HSL palette:

    • Brand Accent (Emerald Green): #0dbd8b (hsl(163, 88%, 41%))
    • Dark Mode Background (Charcoal Slate): #15191e (hsl(216, 18%, 10%))
    • Light Mode Background: #ffffff
    • Typography: Uses "Inter", "Helvetica Neue", sans-serif.

    Timeline Layout Mode

    Setting layoutMode="timeline" changes the message structure:

    • Removes message bubbles for a flat, continuous design.
    • Clusters consecutive messages from the same sender under a single header with reduced padding.
    • Adds a theme-colored left border accent on message hover.

    Federated Badges

    • Federated Room Indicator: A globe icon appears in the header to indicate a federated room.
    • Server Origin Badges: Users from external domains (e.g., @user:matrix.org) receive an emerald-bordered badge displaying their remote domain (e.g., matrix.org).

  10. Manage `ec-token` storage and security

    develop

    After a successful login, the Rocket.Chat server returns an ec-token. EmbeddedChat handles this token in two ways:

    • Local Storage (Default): The token is stored in the browser's local storage. If found on load, it triggers an automatic login.
    • HTTP-Only Cookie (Secure): By setting the secure prop to true, the ec-token is stored as an HTTP-only cookie. This prevents JavaScript access to the token, enhancing security. Note: This requires the EmbeddedChat RC app to be installed on the server to manage the cookie transfer between the RC app and the Rocket.Chat /api/v1/login endpoint.

  12. Authentication Methods for EmbeddedChat

    develop

    EmbeddedChat supports three primary authentication methods:

    1. Token-Based Authentication: Uses a personal access token or a service-specific access token.
    2. Login Credentials: Uses a valid username/email and password.
    3. OAuth Authentication: Uses Rocket.Chat's OAuth configuration. Note: This method requires installing the EmbeddedChat RC App on the Rocket.Chat server.

    Storing the ec-token for Auto Login

    After login, a resume token called ec-token is used for auto-login. You can store this in two ways:

    • Local Storage: Standard browser local storage.
    • HTTP-Only Cookie: More secure, but requires the EmbeddedChat RC App to be installed on the Rocket.Chat server. Use the secure prop to enable this.