Agent Desk Settings Feature & Configuration Guide

Centralized Agent Desk Settings replaces scattered environment variables and config.json values with a tenant-level configuration managed in Unified Admin and consumed by Unified Agent, Agent Manager, and Conversation Manager.

Feature: Agent Desk Settings (env → API / Redis)
Ticket / Branch: 5.2.0_f-CLCC-565
Components: Unified Admin, Unified Agent, Agent Manager, Conversation Manager

Overview

Agent Desk configuration that previously lived in environment variables or config.json is now stored centrally in MongoDB per tenant through Unified Admin → Agent Desk Settings. This creates a single source of truth for Agent Desk behavior while still supporting component-specific consumption patterns.

Component	How it gets settings
Unified Agent	Loads `assets/config.json` for base URLs and feature flags, then merges Agent Desk Settings from the Unified Admin API
Agent Manager	Uses wrap-up settings only via Redis key `{tenantId}:wrapupSettings`, with fallback to Unified Admin API
Conversation Manager	Uses wrap-up settings only via the same Redis key `{tenantId}:wrapupSettings`

Key design point: most Agent Desk settings are consumed directly by Unified Agent, while wrap-up is intentionally distributed through Redis for Agent Manager and Conversation Manager.

Configuration flow

The configuration lifecycle follows a simple publish-and-consume model:

Admin users update settings in Unified Admin UI.
Unified Admin persists the full settings document in MongoDB.
If wrap-up fields change, Unified Admin notifies Agent Manager through POST /wrapup-settings.
Agent Manager normalizes and stores wrap-up values in Redis.
Unified Agent reads from the Admin API, while Conversation Manager reads wrap-up from Redis.

Unified Admin is the authoring system. MongoDB is the persistent store. Redis is the fast distribution layer for wrap-up settings.

Unified Admin

Where to edit

Item	Detail
Menu / page	Agent Desk Settings
Route	`/agent-desk`
Permission resource	`agent-desk-setting` with `view` and `manage`
Save behavior	Updates MongoDB and, when wrap-up fields change, notifies Agent Manager

Editable settings

UI label	Field	Type	Default	Notes
Message Formatting	`isMessageFormattingEnabled`	Boolean	`false`	Conversation formatting support
Text Refine	`isTextRefineEnabled`	Boolean	`false`	AI text refinement
Knowledge Base Search	`isKnowledgeBaseSearchEnabled`	Boolean	`false`	Requires KB URL when enabled
Knowledge Base URL	`knowledgeBaseUrl`	String	`""`	Required when KB search is on
File Sharing	`isFileSharingEnabled`	Boolean	`false`	Conversation attachment support
Emojis	`isEmojisEnabled`	Boolean	`false`	Enables emoji support in chat
Spell Check	`isSpellCheckEnabled`	Boolean	`true`	Enabled by default
Quick Links	`isQuickLinksEnabled`	Boolean	`true`	Header quick links in Agent Desk
Default Home Page	`isDefaultHomePageEnabled`	Boolean	`true`	Default home page behavior
Auto Answer	`isAutoAnswerEnabled`	Boolean	`false`	Not used for Cisco calls
Cisco	`isCiscoEnabled`	Boolean	`false`	Mutually exclusive with CX Voice
CX Voice	`isCxVoiceEnabled`	Boolean	`false`	Mutually exclusive with Cisco
WebRTC Video	`isWebRtcVideoEnabled`	Boolean	`false`	Video capability flag
WebRTC Service Identifier	`webRtcServiceIdentifier`	String	`"00000"`	Service identifier value
Enable Voice Events For CRM	`enableVoiceEventsForCrm`	Boolean	`false`	Cleared if both Cisco and CX Voice are off
Wrap-Up	`isWrapUpEnabled`	Boolean	`false`	Propagates to Agent Manager and Redis
Wrap-Up Time	`wrapUpTime`	Number	`15`	Valid range: 15–1800 seconds
Dashboard Refresh Time	`dashboardRefreshTime`	Number	`10000`	Milliseconds
CRM Events	`isCrmEventsEnabled`	Boolean	`false`	CRM event support
Conversation Participants	`isConversationParticipantsEnabled`	Boolean	`false`	Participant visibility
Show Active Sessions Data	`isShowActiveChannelsDataEnabled`	Boolean	`false`	Session data visibility
Outbound SMS	`isOutboundSmsEnabled`	Boolean	`false`	SMS sending support
Prefix Code	`prefixCode`	String	`"+1"`	Used when SMS is enabled
Close Send SMS Dialog	`isOutboundSmsSendandClose`	Boolean	`false`	Auto-close SMS dialog
Pause Conversation	`holdConversation`	Array	1/3/5/7/10 min	Hold duration options
Inactivity Timeout	`isInactivityTimerEnabled`	Boolean	`false`	Enables inactivity timer
Inactivity Time	`inactivityTimeoutSeconds`	Number	`100`	Valid range when enabled: 30–3600
Bot Suggestion Thresholds	`botSuggestionThresholdColors`	Array	Low/Mid/High bands	Threshold label, color, min, max

API

Base path: {UNIFIED_ADMIN_URL}/agent-desk-settings

Method	Path	Purpose
`GET`	`/agent-desk-settings`	Returns tenant Agent Desk Settings, usually as a single-item array, and seeds missing defaults for existing tenants
`PUT`	`/agent-desk-settings`	Updates settings; request body must include `id`

GET behavior: creates a default document if none exists, or fills newly introduced fields through seeding logic.
PUT behavior: validates with Joi, enforces Cisco/CX Voice mutual exclusion, and sends a wrap-up webhook if isWrapUpEnabled or wrapUpTime changed.

Required Unified Admin config: AGENT_MANAGER_URL must point to Agent Manager. If it is empty, wrap-up notification is skipped and only logged.

Settings catalog

Top-level settings

Field	Type	Default	Consumed by
`isMessageFormattingEnabled`	Boolean	`false`	Unified Agent
`isTextRefineEnabled`	Boolean	`false`	Unified Agent
`isKnowledgeBaseSearchEnabled`	Boolean	`false`	Unified Agent
`knowledgeBaseUrl`	String	`""`	Unified Agent
`isFileSharingEnabled`	Boolean	`false`	Unified Agent
`isEmojisEnabled`	Boolean	`false`	Unified Agent
`isAutoAnswerEnabled`	Boolean	`false`	Unified Agent
`isCiscoEnabled`	Boolean	`false`	Unified Agent
`isCxVoiceEnabled`	Boolean	`false`	Unified Agent
`enableVoiceEventsForCrm`	Boolean	`false`	Unified Agent
`isSpellCheckEnabled`	Boolean	`true`	Unified Agent
`dashboardRefreshTime`	Number	`10000`	Unified Agent
`isCrmEventsEnabled`	Boolean	`false`	Unified Agent
`isQuickLinksEnabled`	Boolean	`true`	Unified Agent
`isDefaultHomePageEnabled`	Boolean	`true`	Unified Agent
`isWebRtcVideoEnabled`	Boolean	`false`	Unified Agent
`webRtcServiceIdentifier`	String	`"00000"`	Unified Agent
`isWrapUpEnabled`	Boolean	`false`	Agent Manager and Conversation Manager via Redis
`wrapUpTime`	Number	`15`	Agent Manager and Conversation Manager via Redis
`isConversationParticipantsEnabled`	Boolean	`false`	Unified Agent
`isShowActiveChannelsDataEnabled`	Boolean	`false`	Unified Agent
`isOutboundSmsEnabled`	Boolean	`false`	Unified Agent
`isOutboundSmsSendandClose`	Boolean	`false`	Unified Agent
`prefixCode`	String	`"+1"`	Unified Agent
`isInactivityTimerEnabled`	Boolean	`false`	Unified Agent
`inactivityTimeoutSeconds`	Number	`100`	Unified Agent
`holdConversation`	Array	1/3/5/7/10 min	Unified Agent
`botSuggestionThresholdColors`	Array	Low/Mid/High	Unified Agent

Nested Cisco settings

Field	Type	Default	Unified Agent maps to
`getQueuesDelay`	Number	`15`	`getQueuesDelay`
`ssoBackendUrl`	String	Sample URL	`ssoBackendUrl`
`isGadget`	Boolean	`true`	`isGadget`
`isSecureLinkEnabled`	Boolean	`false`	`isSecureLinkEnabled`
`boshUrl`	String	Configured value	`boshUrl`
`subBoshUrl`	String	Configured value	`subBoshUrl`
`callVariable`	String	`callVariable1`	`callVariable`
`domain`	String	Configured value	`domain`
`subDomain`	String	Configured value	`subDomain`
`ctiParam`	String	Encrypted value	`ctiParam`
`ctiParam2`	String	Encrypted value	`ctiParam2`
`finesseFlavor`	String	`UCCX`	`finesseFlavor`
`ciscoCcMrd`	String	Configured value	`CISCO_CC_MRD`
`finesseURLForAgent`	String	Configured value	`finesseURLForAgent`
`isFinesseHaEnabled`	Boolean	`false`	`IS_FINESSE_HA_ENABLED`
`secondaryFinesseUrl`	String	Configured value	`SECONDARY_FINESSE_URL`
`autoAnswerDelay`	Number	`5000`	`AUTO_ANSWER_DELAY`
`ciscoServiceIdentifier`	String	`"0000"`	`CISCO_SERVICE_IDENTIFIER`

Nested CX Voice settings

Field	Type	Default	Unified Agent maps to
`autoCallAnswerTimer`	Number	`3`	`AUTO_CALL_ANSWER_TIMER`
`sipMonitoringDn`	String	`"*44"`	`SIP_MONITORING_DN`
`sipExternalDn`	String	`"99887765"`	`SIP_EXTERNAL_DN`
`cxVoiceMrd`	String	Configured value	`CX_VOICE_MRD`
`extStatic`	String	Encrypted value	`EXT_STATIC`
`enableSipLogs`	Boolean	`false`	`ENABLE_SIP_LOGS`
`staticQueueTransferDn`	String	`"99887766"`	`STATIC_QUEUE_TRANSFER_DN`

Agent Manager

Wrap-up storage model

Before	After
Environment variables `IS_WRAP_UP_ENABLED` and `WRAPUP_TIME`	Redis plus Unified Admin API; environment-based config removed

Item	Value
Redis key	`{tenantId}:wrapupSettings`
Stored value	`{ "isWrapUpEnabled": boolean, "wrapUpTime": number }`
Default if missing	`{ isWrapUpEnabled: false, wrapUpTime: 15 }`

Webhook from Unified Admin

Item	Detail
Method / path	`POST /wrapup-settings`
When triggered	When Agent Desk Settings are saved and wrap-up fields changed
Headers	`Content-Type: application/json`, `x-correlation-id`, `tenantid`
Example body	`{ "settingsId": "...", "isWrapUpEnabled": true, "wrapUpTime": 1600, "changedFields": ["isWrapUpEnabled", "wrapUpTime"] }`
Effect	Writes normalized wrap-up values to Redis

Startup behavior initializes tenant wrap-up settings by fetching Unified Admin data and caching it in Redis. During runtime, Agent Manager reads Redis first and falls back to the Admin API only if the key is missing.

Runtime usage: wrap-up settings are referenced in agent.service.js, artemis.service.js, and jms.service.js.

Conversation Manager

Conversation Manager no longer reads wrap-up configuration from environment or common config. It relies entirely on the shared Redis key maintained by Agent Manager or the Admin-to-Agent Manager webhook path.

Item	Detail
Redis key	`{tenantId}:wrapupSettings`
DTO	`com.ef.conversationmanager.dto.WrapUpSettings` with `isWrapUpEnabled` and `wrapUpTime`
API	`ConversationCache.getWrapUpSettings()` via `ConversationCacheImpl`

The main usage point is ChannelSessionEndedEvent, which checks Redis-backed wrap-up settings to decide post-session behavior.

Unified Agent

Load sequence

Load assets/config.json for service URLs, environment values, and bootstrap feature flags.
Call {UNIFIED_ADMIN_URL}/agent-desk-settings and merge migrated settings into runtime config through loadAgentDeskSettings and mergeAgentDeskSettings.
If the Admin call fails, continue using existing defaults or values already present in config.json.
After app load, call getConversationSettings() again for conversation-level UX settings such as emojis, formatting, KB, inactivity, SMS, and participant-related options.

Authentication behavior: /agent-desk-settings is excluded from the auth interceptor so it can be fetched before login.

What remains in config.json

Only non-migrated bootstrap values should remain in config.json or environment templates. These include service URLs, selected feature flags, SIP connectivity settings, timeout values, domain settings, and environment metadata.

Removed from template/env and now sourced from API: Cisco, CX Voice, spell check, CRM events, dashboard refresh, WebRTC flags, secure link, quick links, default home page, and other migrated Agent Desk settings. Wrap-up is also removed from agent bootstrap handling and distributed through Redis for Agent Manager and Conversation Manager.

Runtime effects in Agent Desk

Setting	Effect in Agent Desk
`isQuickLinksEnabled`	Shows or hides the Quick Links button in the header
`isSpellCheckEnabled`	Enables or disables spell check for agent messages
`isEmojisEnabled`	Enables emoji support in chat
`isKnowledgeBaseSearchEnabled` + `knowledgeBaseUrl`	Controls knowledge base search availability in conversations
`isCiscoEnabled` / `isCxVoiceEnabled`	Selects the voice stack and loads associated nested CTI or SIP configuration
Conversation settings	Control participants, file sharing, hold options, inactivity, SMS, and related UX behavior

End-to-end wrap-up flow

Admin opens Agent Desk Settings at /agent-desk.
Admin enables Wrap-Up and sets Wrap-Up Time within the 15–1800 second range.
Unified Admin saves the values to MongoDB.
Unified Admin sends POST {AGENT_MANAGER_URL}/wrapup-settings.
Agent Manager writes the normalized payload to Redis under {tenantId}:wrapupSettings.
Agent Manager uses Redis for wrap-up timers and eligibility checks.
Conversation Manager reads the same Redis key when a channel session ends.

Operational note: if AGENT_MANAGER_URL is not configured, wrap-up changes will not reach Redis until Agent Manager restarts and performs its startup fetch, or until a later successful notification occurs.

Deployment checklist

Unified Admin

Deploy backend and frontend, including the frontend build copied into Backend/src/public
Set AGENT_MANAGER_URL to the Agent Manager base URL
Confirm GET /agent-desk-settings returns a document with the new fields
Confirm the UI shows expected toggles such as Quick Links, Default Home Page, Wrap-Up, Cisco, and CX Voice
Confirm the role includes agent-desk-setting permissions as needed

Unified Agent

Deploy an image with a slim config.json template that excludes migrated keys
Verify UNIFIED_ADMIN_URL is correct
In browser network tools, confirm GET .../agent-desk-settings returns 200 during load
Change a setting in Admin, hard refresh Agent Desk, and verify the behavior updates

Agent Manager

Deploy with Redis-backed wrap-up support and POST /wrapup-settings
Remove legacy IS_WRAP_UP_ENABLED and WRAPUP_TIME variables if still present
Confirm startup writes {tenantId}:wrapupSettings to Redis
Confirm saving wrap-up in Admin updates Redis without restart

Conversation Manager

Deploy with Redis-based WrapUpSettings and no wrap-up env dependency
Verify it shares the same Redis instance and key pattern as Agent Manager

Verification

Check	How to verify
Admin API	Call `GET https://<fqdn>/unified-admin/agent-desk-settings`
Admin UI	Open `/agent-desk` and confirm toggles are visible and save correctly
Agent Desk API merge	Use DevTools Network to inspect `agent-desk-settings` during load and review related config logs
Quick Links	Disable in Admin, refresh Agent Desk, and confirm the header button is hidden
Wrap-up Redis	After saving wrap-up in Admin, verify Redis key `{tenantId}:wrapupSettings` is updated
Wrap-up webhook	Check Admin and Agent Manager logs for `POST /wrapup-settings`
Conversation Manager behavior	Confirm channel session end respects the Redis wrap-up flag

Sample GET response shape

JSON

[
  {
    "id": "...",
    "isMessageFormattingEnabled": false,
    "isTextRefineEnabled": true,
    "isKnowledgeBaseSearchEnabled": true,
    "knowledgeBaseUrl": "https://.../search",
    "isFileSharingEnabled": true,
    "isEmojisEnabled": true,
    "isSpellCheckEnabled": false,
    "isQuickLinksEnabled": true,
    "isDefaultHomePageEnabled": true,
    "isAutoAnswerEnabled": false,
    "isCiscoEnabled": false,
    "isCxVoiceEnabled": false,
    "ciscoSettings": { "...": "..." },
    "cxVoiceSettings": { "...": "..." },
    "isWebRtcVideoEnabled": false,
    "webRtcServiceIdentifier": "00000",
    "enableVoiceEventsForCrm": false,
    "isWrapUpEnabled": false,
    "wrapUpTime": 1600,
    "dashboardRefreshTime": 10000,
    "isCrmEventsEnabled": false,
    "isConversationParticipantsEnabled": false,
    "isShowActiveChannelsDataEnabled": false,
    "isOutboundSmsEnabled": false,
    "isOutboundSmsSendandClose": false,
    "prefixCode": "+1",
    "isInactivityTimerEnabled": false,
    "inactivityTimeoutSeconds": 100,
    "holdConversation": [{ "label": "1 Minute", "value": 1 }],
    "botSuggestionThresholdColors": [{ "label": "high", "color": "green", "min": 50, "max": 100 }],
    "createdAt": "...",
    "updatedAt": "..."
  }
]