@apps-megafy/agentic-chat

Headless React controller for Megafy admission-agent chat experiences. Exposes AdmissionChat — a ready-made controller that composes @apps-megafy/ui components and wires consent, voice input, document upload, camera capture, quick actions, and live agent streaming over WebSocket.

Install

npm install @apps-megafy/agentic-chat @apps-megafy/ui react react-dom

@apps-megafy/ui is a runtime dependency; import its stylesheet once:

import "@apps-megafy/ui/styles.css";

Usage

import { AdmissionChat } from "@apps-megafy/agentic-chat";
import "@apps-megafy/ui/styles.css";

export function AdmissionScreen({ sessionId, currentUser }) {
  return (
    <AdmissionChat
      sessionId={sessionId}
      websocketUrl="wss://agent.example.com/ws"
      agentBaseUrl="https://agent.example.com"
      documentUploadUrl="https://agent.example.com/upload"
      sttUrl="https://agent.example.com/stt"
      consent={{ title: "Consent", body: "…", required: true }}
      onError={(err) => console.error(err)}
    />
  );
}

Props (AdmissionChatProps)

| Prop | Type | Notes | | --- | --- | --- | | sessionId | string | Required. | | websocketUrl | string? | Live agent stream. | | agentBaseUrl | string? | Agent HTTP base. | | documentUploadUrl | string? | Document upload endpoint. | | sttUrl | string? | Speech-to-text endpoint. | | theme | AdmissionChatTheme? | Header title/subtitle + visual config. | | consent | AdmissionConsentConfig? | Consent gate. | | initialMessages | AgentMessage[]? | Seed history. | | inputPlaceholder | string? | | | connectionTimeoutMs | number? | | | className | string? | | | showResetButton | boolean? | | | onResetSession | () => void | | | onDocumentUpload | (file: File) => Promise<AgentAttachment> | | | onError | (error: Error) => void | Surface for the four UI states (loading/success/error/empty). | | onProgress | (progress: AdmissionProgressSummary, complete: boolean) => void | Every progress update the agent sends; the built-in progress bar keeps working regardless. | | onComplete | (progress: AdmissionProgressSummary) => void | The agent reported the session complete (progress frame with complete: true). Use it to lock the chat or swap in a "thank you" screen from the host. May fire more than once if the agent re-sends the frame. | | socketFactory | ((url: string) => WebSocket)? | Injectable socket seam — defaults to new WebSocket(url). Pass a fake implementation to run the chat against a scripted mock (see frontend/admission-chat-mock/mockAgentSocket.ts) or in tests; production widgets omit it. |

Architecture note for Mendix

AdmissionChat connects directly to an external admission-agent backend over WebSocket (the AWS/LLM agent path — Bedrock/Fargate/etc.). It does not use the Mendix Java-Action/Core data path. When embedding in a Mendix widget:

• Pass the agent URLs and sessionId as widget props (declared in the widget XML).
• Use native Mendix callbacks for routing/navigation.
• Role/permission gating (currentUser) belongs in your page controller, not in this component — and it is UX only. Real authorization stays in Mendix access rules.

See the repo root README.md for the full Mendix integration guide.