Features

The package ships a full messaging experience on top of your RealtimeX backend: conversations, messages, presence cues, attachments, and group administration. This page explains what each feature area does and where you configure or customize it.

Most UI surfaces can be restyled or replaced through the components, classNames, and features props. See Customization and Components for slot-level details.

Real-time one-to-one and group conversations run over Socket.IO with REST fallbacks for history and metadata. Messages are sent with an optimistic UI so they appear instantly and reconcile when the server acknowledges.

• Channel list and message list update from the Zustand store as socket events arrive.
• Group threads support admins, permissions, and member management drawers from the header.
• Wire REST filters via queryParams / queryParamsByApi on API Integration.

Users can attach images and files to messages. The package requests S3 presigned URLs, uploads directly from the browser, then sends the resulting file metadata with the message payload.

The optional showNotification helper surfaces toast-style feedback for errors and success states. If you use it, install react-hot-toast as a peer dependency in your host app.

In-app alert banners are also available through useChatAlerts — see Hooks.

Emoji reactions attach to individual messages and render through the MessageReactions slot. The package includes a bundled emoji picker; replace the slot if you need a different picker UX.

Live typing indicators are pushed over the socket as participants type. The indicator appears in the active conversation header/list context and clears when typing stops or a message is sent.

You normally do not subscribe to typing events yourself — the store updates automatically. Advanced diagnostics are covered in Socket Events.

In-chat search finds messages in the active conversation (and related context) using the backend searchMessages and searchMessagesContext endpoints. Results open a contextual jump so users can scroll to the matched message.

The message toolbar exposes common actions: reply, forward, edit (me/everyone), delete (me/everyone), pin, and star. Actions appear through the MessageToolbar slot and respect server permissions / timers configured for your tenant.

Each message tracks sent, delivered, and read states. The MessageStatus slot renders those states (ticks / labels). Receipts update as further socket events arrive after the optimistic send reconciles.

Group owners and admins can manage members, admins, and permissions from header drawers (MembersDrawer, channel details, and related slots). Pin package version 1.1.56+ if you replace those drawers.

The package exposes call buttons and callback hooks via the features prop (showPhoneCall, showVideoCall, onPhoneCall, onVideoCall). You own the WebRTC / VideoSDK integration — the UI only invokes your callbacks with the active channel context.

Tenant call toggles and VideoSDK configuration live in Platform settings on the API side. See Get Settings and Update Settings when enabling calls for a workspace.

After the chat session is ready, the package fetches GET /settings/effective and stores the result in ChatEffectiveSettingsProvider. Those workspace effective settings gate features in the default UI: a denied control stays visible but is disabled, and hovering shows a tooltip with the reason (e.g. “This feature is disabled by your administrator.”). Default components already honor these gates — but custom slot components must honor them too, because the package cannot force-disable arbitrary host JSX.

What the API controls

Gating a custom control

If you replace a whole slot, read the gate with useAdminFeatureGate and wrap the control with AdminPermissionTooltip. Keys: audioCall, videoCall, pushNotification, blockUsers, attachments, groupCreation.

import {
  useAdminFeatureGate,
  AdminPermissionTooltip,
} from "@realtimexsco/live-chat";

function MyVideoCallButton({ onVideoCall, className }) {
  const gate = useAdminFeatureGate("videoCall");

  return (
    <AdminPermissionTooltip
      disabled={!gate.enabled}
      message={gate.disabledReason}
      side="bottom"
    >
      <button
        type="button"
        className={className}
        disabled={!gate.enabled}
        onClick={gate.enabled ? onVideoCall : undefined}
      >
        Video
      </button>
    </AdminPermissionTooltip>
  );
}

Contract for permission-aware controls

• Keep the control visible when denied — never hide it.
• Set disabled={!gate.enabled} and clear onClick when disabled.
• Wrap with AdminPermissionTooltip so the reason shows on hover.
• For raw limits (file size, timers, ceilings, locked policy) read useEffectiveSettingsOptional() — e.g. settings.attachments.maxFileSizeMB or isGroupPermissionLocked("onlyAdminCanSendMessage"). Show a spinner while loading instead of flashing the wrong state.