![Ringle](assets/ringle-logo.png)

# Advanced conversation configuration

## Purpose
Four settings pages tune the conversation engine underneath the flows: Intents controls what the assistant recognizes, LLM Prompts customizes the classifier prompts, Capabilities switches whole behaviors on or off, and Engine Behavior sets timing and clarification defaults.

## Prerequisites
- A tenant role with conversation management permission; members without it do not see these four sidebar items at all.
- Changes on these pages affect the live assistant, so treat every Save as a production change.

## Steps

### Step 1

![conversation-advanced-config, step-01](screenshots/conversation-advanced-config/step-01.png)

**Action:** Click Intents under Conversations & AI in the sidebar.

**What you should see:** Two tabs appear: System Intents (the built-in catalog, count shown in the tab label, 14 in the Demo Auto Shop tenant) and Custom Intents. System intents are grouped by category; the demo tenant shows Navigation, Support, Booking, Capture, and Fallback. Each table shows the intent name, display name, description, a yellow "Yes" chip when the intent can interrupt the current flow, an Enabled switch, and a pencil to customize. The catalog is tenant specific, so the exact intents and categories vary by tenant. The Custom Intents tab lists tenant-defined intents with a Create Intent button.

### Step 2

![conversation-advanced-config, step-02](screenshots/conversation-advanced-config/step-02.png)

**Action:** Click the pencil on a system intent, for example book_appointment. Review the dialog. Then click Cancel.

**What you should see:** The "Customize: book_appointment" dialog (the title names whichever intent you opened) has a Custom Description field ("Used in LLM classification prompts") and a Custom Examples field with one utterance per line ("Sample utterances for this intent"). Saving stores a tenant override, and a Reset to default action then appears on the row. Cancel leaves the catalog untouched.

### Step 3

![conversation-advanced-config, step-03](screenshots/conversation-advanced-config/step-03.png)

**Action:** Click LLM Prompts in the sidebar.

**What you should see:** A table lists each prompt used by the assistant's language-model classifier. Each row shows the prompt key (such as `intent_classification`), a description, its temperature and max tokens, a Source chip (Default, or a warning chip once overridden), and an edit pencil. Prompts cannot be created or deleted, only overridden and reset.

### Step 4

![conversation-advanced-config, step-04](screenshots/conversation-advanced-config/step-04.png)

**Action:** Click the pencil on a prompt. Review the dialog. Then click Cancel.

**What you should see:** The edit dialog shows the full prompt template with its placeholders (like {text} and {intents_list}), the system message, and number fields for Temperature and MaxTokens. Saving stores only the fields you changed as a tenant override. Cancel changes nothing.

### Step 5

![conversation-advanced-config, step-05](screenshots/conversation-advanced-config/step-05.png)

**Action:** Click Capabilities in the sidebar.

**What you should see:** A table lists every conversation capability for the tenant. The Demo Auto Shop tenant shows goodbye, booking, transfer, and greeting; the set is tenant specific, so an ecommerce tenant lists different capabilities such as wismo, return, and subscription. Each row shows its display name, priority, channel chips where the capability is restricted to specific channels (blank when it runs on all), a Source chip, an Enabled switch, and an edit pencil. The edit dialog holds the capability's entry, exit, and resume prompts plus a JSON config block. Like prompts, capabilities can be overridden and reset but not created or deleted.

### Step 6

![conversation-advanced-config, step-06](screenshots/conversation-advanced-config/step-06.png)

**Action:** Click Engine Behavior in the sidebar.

**What you should see:** The page (headed "Conversation Settings") opens on the General tab. It has three timing fields in milliseconds: Dead Air Threshold, TTS First Chunk Threshold, and Welcome Start Threshold. It also has switches for "Treat welcome message as bot speech" and "Enable latency events", a Global DTMF Overrides JSON block (for example mapping key 0 to a transfer), and a "Save general settings" button.

### Step 7

![conversation-advanced-config, step-07](screenshots/conversation-advanced-config/step-07.png)

**Action:** Switch to the Clarification tab.

**What you should see:** The tab holds the clarification behavior for ordering conversations. It has switches for "Always ask about modifiers", "Always clarify ambiguous matches", and "Enable upsell prompts", a Prompt Tone text field, Max Variations and Max Modifiers number fields, and a "Save clarification settings" button.

## Troubleshooting
- Some column headers and dialog labels appear as run-together names such as "PromptKey", "MaxTokens", or "DisplayName": a known cosmetic gap (missing translations); the controls work normally.
- These sidebar items are missing: your role lacks conversation management permission. Ask a tenant owner to adjust your role.
- "Global DTMF overrides must be valid JSON.": the JSON block failed to parse; fix the syntax and save again. The Capabilities config field validates the same way.
- You cannot find a Reset to default action: it only appears on rows that carry a tenant override; rows still on the platform default have nothing to reset.

## Notes
- Routes: `/settings/intents`, `/settings/llm-prompts`, `/settings/capabilities`, and `/settings/engine-behavior`, under the Conversations & AI sidebar group. Source components: `pages/settings/IntentsManagementPage.jsx`, `pages/settings/LlmPromptsManagementPage.jsx`, `pages/settings/CapabilitiesManagementPage.jsx`, and `pages/settings/ConversationSettingsPage.jsx` in the portal app.
- Access is gated at the sidebar by the `conversations.manage` permission; platform admins always see the items. Nothing on the pages themselves is platform-admin-only, so every member who can open them gets the same controls.
- System intents, LLM prompts, and capabilities all follow the same override model: the platform default stays intact, your edits become a tenant override marked by the Source chip, and Reset to default removes the override. Only custom intents support create and delete.
- The captures were taken in the Demo Auto Shop tenant, signed in as the tenant owner, so the pages show that tenant's intents and capabilities. Another demo tenant lists a different catalog.