Skip to main content

AI Chat

Feature NameAI Chat
Feature IDCrestApps.OrchardCore.AI.Chat

Provides UI to interact with AI models using the profiles.

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. Instead, the session is created immediately with an assistant message from the configured Initial prompt, and that message appears in chat history when the page loads or when a new session is started.

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.

ModeDescriptionUI Element
Text Only (default)Standard text-based chat. Users type prompts and receive text responses.—
Audio InputAdds a microphone button (🎤) for speech-to-text dictation. Users speak their prompts, review the transcribed text, and click send manually.Microphone button
ConversationPersistent 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​

  1. Navigate to the AI Profile editor (or AI Profile Template editor for Profile source templates).
  2. 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.
  3. 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.
  4. 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​

  1. Click the microphone button to start recording.
  2. Speak your prompt — the button shows a pulsing red stop icon while recording.
  3. Audio is streamed to the server in real-time via SignalR as the user speaks (chunks are sent approximately every second).
  4. 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.
  5. Click the stop button (or the transcription finishes automatically when you stop speaking).
  6. The complete transcribed text appears in the input field for review or editing before sending as a prompt.

How Conversation Mode Works​

  1. Click the headset button to start conversation mode.
  2. The microphone button, send button, and text input are hidden — a persistent audio stream opens to the server.
  3. Speak naturally — your speech is continuously streamed to the server and transcribed in real time.
  4. When a complete utterance is recognized, it is automatically displayed as a user message in the chat and sent to the AI.
  5. 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.
  6. 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.
  7. The stream stays open for continuous back-and-forth conversation — no need to click send between turns.
  8. 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.

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​

Screen cast of the admin chat

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.

Admin Chat Widget​

Feature NameAI Chat Admin Widget
Feature IDCrestApps.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.

Enabling the Admin Widget​

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

Configuring the Admin Widget​

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

Frontend Chat Widget​

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.

Adding the Frontend Widget​

  1. Ensure the Widgets feature (OrchardCore.Widgets) is enabled.
  2. Go to Design > Widgets in the admin menu.
  3. Add a new AI Chat Widget to the desired zone (e.g., Footer, Content).
  4. Configure the widget by selecting the AI chat profile and optionally choosing a prompt template.

Frontend Widget Screen Cast​

Screen cast of the frontend widget

Chat Analytics​

Feature NameAI Chat Analytics
Feature IDCrestApps.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.