Version: Latest

AI Chat


Feature Name	AI Chat
Feature ID	`CrestApps.OrchardCore.AI.Chat`

Provides UI to interact with AI models using the profiles.

The screencast below creates a chat-type AI profile on the gpt-4.1-mini deployment, shows it on the admin menu, and then opens its chat to ask the model a question — all starting from the admin dashboard.

AI Chat Feature

The AI Chat feature adds profile-driven chat capabilities to AI Services. Once enabled, any chat-type AI profile with the Show On Admin Menu option appears under Artificial Intelligence in the admin menu.

AI profiles are source-agnostic in the admin UI. When you click Add Profile, Orchard Core opens the profile editor directly, and the selected chat and utility deployments determine which client and model are used.

AI Profile and Template Editor Layout

The AI Profile editor groups the most common profile settings into five cards at the top of the page:

General — title, technical name, data source, profile type, orchestrator, and admin menu visibility
Deployments — chat deployment and utility deployment
Interactions — title behavior, welcome/initial prompt behavior, chat mode, and per-profile user memory. Prompt subject appears only for Template generated prompt profiles.
Instructions — prompt template selection, template-specific prompt text, and system instructions
Parameters — model tuning values and data-source retrieval parameters

Profile-source AI Templates use the same top-level card grouping:

General — title, technical name, category, profile type, orchestrator, response handler, data source, and admin menu visibility
Deployments — chat deployment and utility deployment
Interactions — title behavior, welcome message, chat mode, and per-template user memory. Prompt subject appears only for Template generated prompt profile-source templates.
Instructions — prompt template text and system instructions
Parameters — model tuning values and data-source retrieval parameters

Additional advanced sections such as capabilities, response handling, analytics, documents, and post-session processing continue to appear below these cards in their existing sections.

For chat profiles, the required Past messages included parameter loads the default value automatically when a profile is opened without an explicit saved value.

When the AI Documents features are enabled, the Knowledge tab for AI Profiles, profile-source AI Templates, and Chat Interactions also exposes a Document retrieval mode selector. Leaving it blank uses the site default from Settings → Artificial Intelligence → Documents. Chunk keeps chunk-level context, while Hierarchical retrieves matching chunks and then injects the full text of the matched documents.

Note: This feature does not provide completion client implementations (e.g., OpenAI, Azure OpenAI, etc.). To enable chat capabilities, you must enable at least one feature that implements an AI completion client, such as:

OpenAI AI Chat (CrestApps.OrchardCore.OpenAI): AI-powered chat using OpenAI service.
Azure OpenAI Chat (CrestApps.OrchardCore.OpenAI.Azure): AI services using Azure OpenAI models.
Azure AI Inference Chat (CrestApps.OrchardCore.AzureAIInference): AI services using Azure AI Inference (GitHub models) models.
Ollama AI Chat (CrestApps.OrchardCore.Ollama): AI-powered chat using Ollama service.

Welcome Message Behavior

When an AI profile has a Welcome Message configured, it is displayed as placeholder text for new sessions. It is not automatically added to the model conversation history.

If Add initial prompt is enabled on the profile, the welcome message is ignored for new sessions. The initial prompt is now saved lazily: Orchard creates and persists the chat session only after the visitor sends the first real message, then the configured assistant Initial prompt is inserted ahead of that first user prompt in the stored conversation history.

This avoids creating empty anonymous chat sessions just because a page or widget loaded.

Chat Mode

AI Chat supports three chat modes that control how users interact with the AI. The Chat Mode dropdown appears on the AI Profile editor (and AI Profile Template editor for Profile source templates) only for profiles of type Chat.

Mode	Description	UI Element
Text Only (default)	Standard text-based chat. Users type prompts and receive text responses.	—
Audio Input	Adds a microphone button (🎤) for speech-to-text dictation. Users speak their prompts, review the transcribed text, and click send manually.	Microphone button
Conversation	Persistent two-way voice interaction like ChatGPT voice mode. A continuous audio stream stays open — the user speaks, the AI responds with both text and voice simultaneously.	Headset button

Prerequisites

Audio Input requires a Default Speech-to-Text Deployment configured in Settings → Artificial Intelligence → Default Deployments (any deployment supporting the ISpeechToTextClient interface, such as Azure Speech or OpenAI Whisper).
Conversation requires both a Default Speech-to-Text Deployment and a Default Text-to-Speech Deployment configured in default deployment settings.
Optionally, set a Default Text-to-Speech Voice in Settings → Artificial Intelligence → Default Deployments. This voice is used when no profile-specific voice is selected.
If an AI Profile leaves its chat model set to Default deployment, chat sessions use Default Chat Deployment from Settings → Artificial Intelligence → Default Deployments after checking the connection-level default.

Configuring Chat Mode

Navigate to the AI Profile editor (or AI Profile Template editor for Profile source templates).
Select the desired option from the Chat Mode dropdown. The dropdown only appears for Chat profile types and when the required default deployments are configured.
When Conversation is selected, a Voice dropdown appears. Available voices are fetched from the configured text-to-speech provider. If no voice is selected, the default voice from site settings (or the provider's default) is used.
Save the profile.

Once configured, the selected chat mode applies to all chat UIs associated with that profile:

Admin session chat
Frontend widget
Admin widget

How Audio Input Works

Click the microphone button to start recording.
Speak your prompt — the button shows a pulsing red stop icon while recording.
Audio is streamed to the server in real-time via SignalR as the user speaks (chunks are sent approximately every second).
The server transcribes audio using the configured speech-to-text provider and streams transcript text back to the UI as it becomes available — you see words appear while still speaking.
Click the stop button (or the transcription finishes automatically when you stop speaking).
The complete transcribed text appears in the input field for review or editing before sending as a prompt.

How Conversation Mode Works

Click the headset button to start conversation mode.
The microphone button, send button, and text input are hidden — a persistent audio stream opens to the server.
Speak naturally — your speech is continuously streamed to the server and transcribed in real time.
When a complete utterance is recognized, it is automatically displayed as a user message in the chat and sent to the AI.
The AI response streams to the chat as text and is simultaneously synthesized to speech — you see the text appear while hearing it read aloud.
If you start speaking while the AI is still responding, the AI's current response (both text and audio) is interrupted, and your new prompt is processed instead.
The stream stays open for continuous back-and-forth conversation — no need to click send between turns.
Click the headset button again to end the conversation. The microphone, send button, and text input are restored.

info

If the speech-to-text service encounters an error (e.g., authentication failure), the error is reported immediately and the recording stops automatically — the microphone button resets so you can try again.

info

Text-to-speech synthesis occurs after the full response text has been received — it does not interrupt or delay the text streaming experience.

Text-to-Speech Playback

Even when a profile is not using the full Conversation chat mode, you can enable on-demand text-to-speech playback for AI-generated messages. When enabled, a playback button (🔊) appears on each AI message, allowing users to click and listen to the response as synthesized speech.

Enabling TTS Playback

TTS playback can be enabled at two levels:

Site level (Chat Interactions): Navigate to Settings → Artificial Intelligence → Chat Interactions and check Enable text-to-speech playback. This enables playback across all Chat Interaction sessions.
Profile level: On the AI Profile editor, under the Chat Mode section, check Enable text-to-speech playback. This enables playback for all chat UIs associated with that specific profile.

Prerequisites

A Default Text-to-Speech Deployment must be configured in Settings → Artificial Intelligence → Default Deployments.
The playback feature works with any chat mode (Text Only, Audio Input, or Conversation). In Conversation mode, TTS is already built-in and always active.

Behavior

When a user clicks the playback button on a message, the text is sent to the configured TTS provider and audio is streamed back to the browser.
Message actions appear at the bottom-right of each response so they stay aligned above the divider line instead of covering the top edge of the message.
During playback, the playback button switches between play and pause, stays highlighted while audio is active, and starting another message playback automatically stops the current one.
In Conversation mode, the per-message playback button is hidden so the live voice conversation is not interrupted by manual playback.
Users can stop playback by clicking the button again.

Session document uploads

If a profile allows session document uploads or session image uploads, the chat UI keeps restored widget sessions aligned with the current profile before uploading files. This avoids sending attachment requests through a different profile.

The admin and frontend chat widgets restore their saved toggle and panel positions before the chat app finishes initializing.

The admin session chat now shows the same compact Supported formats note above the input attachment bar that the widgets already expose, so users can see the exact upload extensions allowed for the current profile. Document extensions follow the profile's Allow session document uploads setting, and image extensions only appear when Allow session image uploads is enabled and a vision deployment is available.

The module packages the upstream CSS source maps for the main chat UI and widget styles alongside the compiled assets, so browser developer tools can resolve ai-chat.css.map and chat-widget.css.map without 404 warnings.

By default, session-document uploads are stored on the local file system through the shared AI Documents storage pipeline. If you want widget uploads stored in Azure Blob Storage instead, enable CrestApps.OrchardCore.AI.Documents.Azure and configure it as described in AI Documents - Azure Blob Storage.

Citations and references

When a chat response includes document markers such as [doc:1], the AI Chat UIs convert them into superscript citations and render a linked reference list below the assistant message when a resolver can provide a URL for the reference.

This linked citation rendering now applies consistently across the admin chat UI, the admin widget, and the frontend widget.

Admin Chat User Interface

Invoking Utility and Agent Profiles

For Utility and Agent profile types, the AI profile list includes an Invoke Profile action in the actions menu. Clicking Invoke Profile opens a dedicated single-response screen where you can:

Send a message to the profile and see the streamed response in real time.
Each new message clears the previous response so only the latest prompt and its reply are visible.
Invoke your profile without creating persistent chat sessions.

This is useful for quickly iterating on system instructions, verifying tool integrations, or confirming that the profile produces the expected output.


Feature Name	AI Chat Admin Widget
Feature ID	`CrestApps.OrchardCore.AI.Chat.AdminWidget`

Provides a floating AI chat widget on every admin page, allowing users to interact with a predefined AI profile.

The AI Chat Admin Widget adds a floating chat widget to the Orchard Core admin dashboard. This allows administrators to interact with AI directly from any admin page without navigating away.

When session uploads are enabled for the selected profile, attached files are shown in a dedicated bar above the message input so the input width is preserved, each attachment keeps a visible remove button, and the supported-formats note stays compact instead of dominating the widget.

Referenced responses use the same citation rendering as the main admin chat UI, so [doc:N] markers are shown as superscript links with a matching reference list instead of raw marker text.

Go to Tools > Features in the admin menu.
Search for AI Chat Admin Widget and enable it.
The floating chat widget will appear in the bottom-right corner of the admin dashboard.

Navigate to Settings → Artificial Intelligence → Admin Widget to configure:

Profile: Select the AI chat profile to use for the admin widget.
Max Sessions: Set the maximum number of previous chat sessions displayed in the history panel (1–50).
Primary Color: Customize the widget's primary color (header, toggle button). Defaults to #41b670 (Orchard Core green).
:::tip Pro Tip It's best to enable Orchard Core AI Agent (i.e., CrestApps.OrchardCore.AI.Agent). Then when creating a profile, select all available capabilities to allow the profile to perform tasks on your website. :::

The screencast below enables the AI Chat Admin Widget feature, creates a chat profile with all tool capabilities selected, points the widget at that profile in Settings → Artificial Intelligence → Admin Widget, and then opens the floating widget to ask the assistant a question it answers using its tools.

A frontend chat widget is available to add to your site's public-facing pages using the Orchard Core Widgets system. This allows site visitors to interact with AI chat directly on the frontend.

When the widget's profile allows session document uploads or session image uploads, file attachments are rendered above the input row instead of beside it, matching the admin widget layout, keeping the remove button visible for each attached file, and reducing the visual weight of the supported-formats note.

When the response contains references, the widget also renders [doc:N] markers as superscript citations with linked references beneath the assistant message.

The frontend widget also normalizes theme paragraph spacing inside rendered chat messages so theme-level p margins and padding do not add extra blank space above or below each response.

Frontend widgets now also work with the shared anonymous-visitor protection flow:

Anonymous visitors receive a stable first-party visitor cookie for more accurate unique-visitor analytics.
Chat message throttling and anonymous session-start throttling use that visitor identity together with the configured remote-address mode.
Widgets no longer auto-create sessions on page load just because a profile has an initial prompt.
Settings → Artificial Intelligence now includes Prompt security and Anonymous visitor identity sections so operators can tune rate limits, prompt filtering, and remote-address handling.

To show the widget on every page of the site, place it in a layer whose rule always evaluates to true:

Ensure the Widgets and Layers features are enabled.
Create a dedicated AI chat profile (for example, a public-facing Website Assistant profile of type Chat).
Go to Design > Layers and create a new layer (for example, Global).
Edit the layer, add a Boolean rule, and keep its value set to True so the layer is always active.
Back on the Layers screen, use the Add Widget menu on the target zone (for example, Footer) and add an Artificial Intelligence Chat widget.
Select the Global layer and the AI chat profile you created, then publish the widget.
Visit any public page and open the floating chat widget to talk to your assistant.

The following screen cast walks through creating a public-facing profile, adding an always-on layer with a Boolean rule, placing the AI Chat widget in the footer zone, and chatting with it from the site's home page.

Security and Visitor Identity Settings

Both the admin widget and the frontend widget share a common protection layer that guards against prompt injection, prompt leakage, abusive traffic, and anonymous session churn. These options are configured per tenant under Settings > Artificial Intelligence, and require the Manage AI Profiles permission.

Saving either section may restart the tenant so the updated options take effect.

Prompt Security

The Prompt Security section tunes the shared AI chat protections.

Setting	Default	Description
Enable injection detection	Enabled	Blocks known prompt-injection and instruction-override patterns before they reach the model.
Enable output filtering	Enabled	Filters generated responses for leaked system prompts, tool details, and unsafe disclosures.
Enable security preamble	Enabled	Prepends a hardened security instruction to chat system prompts.
Enable input delimiters	Enabled	Wraps user input with clear boundaries so the model can distinguish user text from system instructions.
Enable audit logging	Enabled	Records prompt security decisions for diagnostics and abuse investigations.
Maximum prompt length	`8000`	Prompts longer than this character count are rejected. Must be between `1` and `100000`.
Blocking threshold	`High`	Prompts classified at or above this risk level (`None`, `Low`, `Medium`, `High`, `Critical`) are blocked.
Maximum messages per window	`20`	How many chat messages one rate-limit partition can send within the message window. Set to `0` to disable message throttling.
Message rate-limit window (seconds)	`60`	Duration of the shared chat message rate-limit window. Must be between `1` and `86400`.
Maximum anonymous sessions per window	`5`	Limits how many new anonymous chat sessions can be started within the anonymous session window. Set to `0` to disable anonymous session-start throttling.
Anonymous session window (seconds)	`600`	Duration of the anonymous chat session-start rate-limit window. Must be between `1` and `86400`.

Message and session-start throttling are keyed by the resolved visitor identity (authenticated user id or anonymous visitor id) together with the configured remote-address mode described below.

Per-profile throttle overrides

The four anti-spam throttle limits above are site-wide defaults. Individual AI profiles can raise or lower them for their own use case from a Prompt Security tab on the AI Profile editor, and AI profile templates (source Profile) can seed the same overrides so a template acts as a reusable throttle preset.

Override	Behavior
Maximum messages per window	When left blank, inherits the site default. Set to `0` to disable message throttling for this profile only.
Message rate-limit window (seconds)	When left blank, inherits the site default. Must be between `1` and `86400`.
Maximum anonymous sessions per window	When left blank, inherits the site default. Set to `0` to disable anonymous session-start throttling for this profile only.
Anonymous session window (seconds)	When left blank, inherits the site default. Must be between `1` and `86400`.

Each override is optional and independent: an unset field always falls back to the corresponding site-wide default, so a profile can override only the message limit while still inheriting the anonymous session limits. Overrides are stored on the profile settings and applied by the chat message and session-start rate limiters. When a profile is created from a profile-source template, the template's throttle overrides are copied onto the new profile. The higher-level prompt-injection, output-filtering, and prompt-length guards remain site-wide only and cannot be overridden per profile.

Anonymous Visitor Identity

The Visitor Identity section controls how anonymous widget visitors are tracked for unique-visitor analytics, abuse controls, and optional remote-address storage. Anonymous visitors receive a stable first-party cookie during page load so repeat visits are recognized as the same visitor instead of a new one for each chat session.

Setting	Default	Description
Visitor cookie name	`crestapps-ai-visitor`	Stable first-party cookie used to identify anonymous visitors across chat sessions.
Cookie lifetime (days)	`180`	How long the anonymous visitor cookie remains valid before a new visitor identity is issued. Must be between `1` and `3650`.
Remote address storage mode	`Hashed`	How the remote address is captured. See the modes below.
Remote address hash salt	`CrestApps.Core.AI.VisitorIdentity`	Application-specific salt used when hashing remote addresses for abuse controls. Required for the `Hashed` and `Encrypted` modes.

The Remote address storage mode supports the following values:

Disabled — do not capture or persist any remote-address data.
Hashed (recommended) — store only a salted hash of the remote address for privacy-first abuse controls.
Plain text — store the remote address in plain text for operational controls such as blocklists.
Encrypted — store the remote address encrypted at rest with Data Protection while still using a salted hash for throttling keys.

info

The remote-address value is read from the X-Forwarded-For header when present, otherwise from the connection remote IP address. When running behind a reverse proxy, make sure forwarded headers are configured so the correct visitor address is captured.

Chat Analytics


Feature Name	AI Chat Analytics
Feature ID	`CrestApps.OrchardCore.AI.Chat.Analytics`

Provides comprehensive analytics and reporting for AI chat sessions, including conversation metrics, performance tracking, user segmentation, and feedback analysis.

For complete documentation, see the AI Chat Analytics guide.

AI Chat