AI-Service documentation

The OX AI-Service integrates 3rd party AIs in App Suite UI, currently ChatGPT from OpenAI, Anthropic Claude on AWS Bedrock or localAI compatible models.

Configuration

The AI Service delivers the App Suite UI plugin, it needs to be added to the baseUrls configuration to ensure the UI Service can fetch the frontend code.

Add the AI Service url (K8s url) to the list of baseUrls of the UI Service configuration. This is needed to ensure that the AI integration's code is send to the user's browser.

Example config map

# hostnames may differ in your setup
baseUrls:
  - http://core-ui
  - http://ai-service
  - http://switchboard

Further reading: UI Service Config map

Capability and Feature toggle

Capability: ai-service

Feature toggle: ai

Requirements

Ensure the following prerequisites are met to run the AI-Service App Suite plugin:

1. A running Switchboard in your stack is needed to run the AI Service. (Switchboard is needed for service-to-service authentication)
2. You are using the Provider Edition (PE) of OX App Suite. This needs a paid App Suite Subscription (For more information contact Sales)
3. The mandatory user config is set for each user that should be able to use the AI integration, see the next chapter

How to enable for users

By default, AI integration is disabled for all users. To enable the feature for users, add the following configurations:

1. Add capability ai-service which indicates a running AI-Service in your deployment
2. Enable the feature toggle for users via

io.ox/core//features/ai = true

3. Set the public available hostname for AI service in the user configuration

io.ox/core//ai/baseURL = https://ai-service.your.deployment.com

Additional AI features

Besides the basic feature set, more advanced features can be turned on via separate switches.

Chat

The AI chat allows a user to chat with the AI. There is a separate feature toggle for this.

config:
  features:
    chat: true

This enables or disables the chat in App Suite UI.

You can also configure the assistant globally by providing context with a system prompt. This prompt will be injected in every conversation as a start message invisible to the end user. Set chatAssistantContext on AI Service config, default is "You are a helpful AI assistant."

Example:

chatAssistantContext: "You are a helpful AI assistant. Your name is Hal 9000."

The frontend part can be configured via the following settings:

# will be available as "config.yaml" in config map
config:
  chat:
    # Automatically open the Chat window for all users with the AI feature on the first run,
    # e.g. after updating to the most recent AI Service. This is helpful
    # to boost AI engagement and make the feature visible.
    autoOpenOnFirstRun: true
    # Add the AI Chat as App in the the App Launcher
    showLauncher: true
    # Add the AI Chat as Icon on the right side in the App Suite toolbar (next to the notification icon)
    showTopRightIcon: true
    # This configures the time to live (TTL) for the chat history.
    history:
      # given in days (0 = keep forever)
      pruneChatsOlderThan: 0

Typeahead for mail compose

The typeahead feature provides automatic text predictions while composing emails. Using AI, it generates text that either completes a sentence or aligns with the overall context. Predictions can be triggered manually by pressing Ctrl+Space during mail composition or will appear automatically after the cursor remains idle for a set period (e.g., 3, 5, or 10 seconds).

This feature includes a dedicated toggle, allowing it to be enabled or disabled for all users.

config:
  features:
    typeahead: false

When enabled, this feature is opt-in, requiring users to acknowledge that the AI will process their email text to generate predictions.

The AI settings panel provides additional user options for this feature, allowing control over whether predictions are shown automatically, only when using a keyboard shortcut, or not at all.

Automatic email translation

With the automatic email translation feature the user can translate emails into their set language automatically.

This feature includes a dedicated toggle, allowing it to be enabled or disabled for all users.

config:
  features:
    autoTranslate: true

The feature can detect the language of an email and will translate it based on the settings for this language. The user can set which language they want to always translate and which languages should never be translated. Currently the following languages can be detected: German, French, English, Spanish, Italian There is a dedicated settings section to manage this. If the language of an email is not detected automatically the user can always choose to manually translate an email via the ai dropdown menu.

Automatic email summaries

The automatic email summary feature uses AI to generate short, easy-to-understand summaries for emails. This helps users grasp the main message without reading the full content. Summaries are created for the most recent emails as soon as users open their inbox.

This feature can be globally enabled or disabled via a configuration toggle:

config:
  features:
    autoSummary: true

How It Works

Once enabled at the system level, users must individually activate the feature in their personal AI settings before it takes effect for them.

After activation:

• The feature generates summaries for the latest 10 emails in the user's inbox.
• A summary section is added to each processed email.
• Summaries appear in the list view and the detail view.
• Users can disable the feature at any time through their personal AI settings.

Each user has a dedicated feature flag stored in their preferences (under io.ox/core//features/.user/ai-autosummary). This setting is false by default, meaning users must opt in to start receiving summaries.

Additional Configuration

config:
  summaries:
    maxAgeDays: 30
    messageLimit: 10

• messageLimit controls how many emails are automatically summarized at once. This limit is not visible to users but helps prevent excessive API usage when a user has many unread emails.
• maxAgeDays defines how long summaries are cached in the database.

Auto Categorize / Smart Inbox Categories

This feature uses the same underlying approach as Automatic Email Summaries. Emails in the user's inbox are analyzed by the AI to determine whether they fit into one of the predefined inbox categories (e.g., Purchases or Promotions). If no suitable category is identified, the email remains under General. If a match is found, the email is automatically moved to the corresponding category. End users also receive visual cues to understand when and how categorization has occurred.

Therefore, this feature depends on Inbox Categories, which need to be properly configured in App Suite Middleware.

The feature can be globally enabled or disabled via a configuration toggle:

config:
  features:
    autoCategorize: true

Engage Idle AI Users

To encourage users to explore AI features, it may be helpful to remind them about these features. A simple approach is to display the AI Tour again after a certain period of inactivity.

config:
  tour:
    remindAfterIdleDays: -1

If a user has already seen the tour but does not use any AI feature within the specified number of days, the tour will reappear exactly once. -1 means disabled.

Note: This feature relies on the date of the user's initial consent to determine whether any AI features have been used during the defined period.

Upsell configuration

AI integration supports the App Suite UI upsell functionality. To enable upsell for the AI features, set the following frontend configuration:

io.ox/core//upsell/activated = true
io.ox/core//upsell/enabled/ai-service = true
io.ox/core//features/ai = true

Remove the capability ai-service for all users that should see the upsell triggers. When enabled, all AI buttons and dropdowns are shown in the UI but will trigger an upsell event on the ox object.

Error Messages

User facing error messages can be customized:

config:
  customStrings:
    errors:
      # Error message when moderation fails due to inappropriate content.
      # Default: "Inappropriate content detected. Please try again with different input."
      moderation:
        en: ''
      # Error message when the AI service is unavailable
      # Default: "API request failed. The service might be unavailable. Please try again in a few minutes."
      unavailable:
        en: ''

Language support and i18n

Supported languages in the AI frontend

The AI frontend is translated in the following languages

Fallback language is always English (en_US)

LLM language support

Not every LLM that can be connected offers the same level of language support. This is important, as users interact directly with the LLM through AI Chat and other user-generated input (e.g., when composing emails).

For ChatGPT 4o and newer, the following table categorizes languages based on their level of support:

For reference:

• The LLM supports many languages, categorized by proficiency levels (e.g., Top Tier, Strong, Functional).
• The UI is translated into a subset of these languages, covering those with strong user demand and reliable localization and matching the most important languages in App Suite

This means that while users can interact with the LLM in many languages, the application interface itself is only available in the languages listed above. As a fallback users are always able to interact with the Chat e.g in English.

Translation feature

The AI Integration includes a dedicated translation feature for emails. By clicking on the AI dropdown in the email toolbar, users can choose to translate emails into their preferred language.

The first option always translates the email into the user's currently set locale. For example, if the user's UI language is set to German, we assume this is their preferred language for translations. The second option is always English, as it is the most commonly used language in our context and serves as a reliable intermediary for translating foreign languages using the LLM.

The following languages are currently supported for translation. This list may change in the future. For UX reasons, we do not include every possible language, as an excessively long dropdown would negatively impact usability.