@webex/contact-center 3.12.0-llmrefactor.2 → 3.12.0-llmrefactor.3

package/src/services/task/state-machine/uiControlsComputer.ts

@@ -3,6 +3,7 @@
  */
 
 import {
+  CONSULT_TRANSFER_DESTINATION_TYPE,
   InteractionUIControls,
   TASK_CHANNEL_TYPE,
   TaskData,
@@ -11,6 +12,10 @@ import {
   VOICE_VARIANT,
 } from '../types';
 import {TaskContext, UIControlConfig} from './types';
+import {
+  getWebexCallingDeviceDetailsForAgent,
+  isWxAppEngagedForControls,
+} from '../WebexCallingUtils';
 import {TaskState, MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE, INTERACTION_STATE} from './constants';
 import {
   getIsCustomerInCall,
@@ -20,11 +25,41 @@ import {
   getIsConsultedAgentForControls,
   getServerHoldStateForControls,
 } from '../TaskUtils';
+import {INBOUND_DIRECTION, OUTDIAL_DIRECTION} from '../../../constants';
+import {COLLABORATION_ACCESS} from '../../config/constants';
+
+type DestinationControls = TaskUIControls['consultTransferDestinations'];
 
 const DISABLED = {isVisible: false, isEnabled: false} as const;
 const VISIBLE_ENABLED = {isVisible: true, isEnabled: true} as const;
 const VISIBLE_DISABLED = {isVisible: true, isEnabled: false} as const;
 
+/** wxApp telephony controls live on the main leg only (mute/keypad via wxApp APIs). */
+function withWxAppTelephonyControls(
+  controls: InteractionUIControls,
+  isWxAppEngaged: boolean,
+  currentLeg: TaskUILeg,
+  isWrappingUp: boolean
+): InteractionUIControls {
+  if (!isWxAppEngaged || isWrappingUp) {
+    return controls;
+  }
+
+  if (currentLeg === 'main') {
+    return {
+      ...controls,
+      mute: VISIBLE_ENABLED,
+      keypad: VISIBLE_ENABLED,
+    };
+  }
+
+  return {
+    ...controls,
+    mute: DISABLED,
+    keypad: DISABLED,
+  };
+}
+
 function getDefaultInteractionUIControls(): InteractionUIControls {
   return {
     accept: DISABLED,
@@ -43,18 +78,24 @@ function getDefaultInteractionUIControls(): InteractionUIControls {
     transferConference: DISABLED,
     mergeToConference: DISABLED,
     switch: DISABLED,
+    keypad: DISABLED,
   };
 }
 
 function createTaskUIControls(
   main: InteractionUIControls,
   consult: InteractionUIControls,
-  activeLeg: TaskUILeg
+  activeLeg: TaskUILeg,
+  consultTransferDestinations: DestinationControls = {
+    consult: [],
+    transfer: [],
+  }
 ): TaskUIControls {
   return {
     main,
     consult,
     activeLeg,
+    consultTransferDestinations,
   };
 }
 
@@ -66,6 +107,53 @@ export function getDefaultUIControls(): TaskUIControls {
   );
 }
 
+function getConsultTransferDestinations(
+  config: UIControlConfig,
+  taskData?: TaskData | null
+): DestinationControls {
+  const destinationConfig = config.consultTransferConfig;
+  if (!destinationConfig) {
+    return {consult: [], transfer: []};
+  }
+
+  const isVoice = config.channelType === TASK_CHANNEL_TYPE.VOICE;
+  const interaction = taskData?.interaction;
+  const direction = interaction?.contactDirection?.type?.toUpperCase();
+  const destinations: DestinationControls = {
+    consult: [],
+    transfer: [],
+  };
+
+  if (destinationConfig.accessBuddyTeam?.toUpperCase() !== COLLABORATION_ACCESS.NONE) {
+    destinations.consult.push(CONSULT_TRANSFER_DESTINATION_TYPE.AGENT);
+    destinations.transfer.push(CONSULT_TRANSFER_DESTINATION_TYPE.AGENT);
+  }
+
+  if (destinationConfig.accessQueue?.toUpperCase() !== COLLABORATION_ACCESS.NONE) {
+    const canConsultQueue = !isVoice || destinationConfig.allowConsultToQueue;
+    const canTransferQueue =
+      !isVoice ||
+      direction === INBOUND_DIRECTION ||
+      (direction === OUTDIAL_DIRECTION &&
+        interaction?.callProcessingDetails?.outdialTransferToQueueEnabled === true);
+
+    if (canConsultQueue) destinations.consult.push(CONSULT_TRANSFER_DESTINATION_TYPE.QUEUE);
+    if (canTransferQueue) destinations.transfer.push(CONSULT_TRANSFER_DESTINATION_TYPE.QUEUE);
+  }
+
+  if (isVoice) {
+    destinations.consult.push(CONSULT_TRANSFER_DESTINATION_TYPE.DIALNUMBER);
+    destinations.transfer.push(CONSULT_TRANSFER_DESTINATION_TYPE.DIALNUMBER);
+
+    if (destinationConfig.accessEntryPoint?.toUpperCase() !== COLLABORATION_ACCESS.NONE) {
+      destinations.consult.push(CONSULT_TRANSFER_DESTINATION_TYPE.ENTRYPOINT);
+      destinations.transfer.push(CONSULT_TRANSFER_DESTINATION_TYPE.ENTRYPOINT);
+    }
+  }
+
+  return destinations;
+}
+
 /** Consult media must exist on the interaction payload, not only as a stale resource id. */
 function hasConsultMediaInInteraction(
   interaction: TaskData['interaction'] | undefined,
@@ -134,6 +222,23 @@ function computeVoiceInteractionUIControls(
     interaction && mainCallId ? getConferenceParticipantsCount(interaction, mainCallId) : 0;
   const maxParticipants = participantCount >= MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE;
   const selfAgentId = config.agentId ?? taskData?.agentId;
+  const enableWxBetterTogether = config.enableWxBetterTogether ?? false;
+  const wxAppDeviceDetails = enableWxBetterTogether
+    ? getWebexCallingDeviceDetailsForAgent(selfAgentId, interaction?.participants)
+    : undefined;
+  const isWxAppParticipant = enableWxBetterTogether && wxAppDeviceDetails?.deviceType === 'wxApp';
+  const isWxAppOffer =
+    isWxAppParticipant && Boolean(wxAppDeviceDetails) && state === TaskState.OFFERED;
+  const isWxAppInboundOffer = isWxAppOffer && !isOutdial;
+  const isWxAppOutdialOffer = isWxAppOffer && isOutdial;
+  const wxAppAnswerPending = config.wxAppAnswerPending ?? false;
+  const wxAppAcceptInFlight = config.wxAppAcceptInFlight ?? false;
+  const isWxAppEngaged = isWxAppEngagedForControls(
+    enableWxBetterTogether,
+    selfAgentId,
+    interaction?.participants,
+    state
+  );
   const consultInProgress = getIsConsultInProgressForConferenceControls(
     interaction,
     mainCallId,
@@ -376,37 +481,52 @@ function computeVoiceInteractionUIControls(
         ? VISIBLE_ENABLED
         : DISABLED;
 
-    return {
-      ...getDefaultInteractionUIControls(),
-      hold: VISIBLE_ENABLED,
-      transfer: VISIBLE_ENABLED,
-      consult: VISIBLE_ENABLED,
-      recording: recordingControl,
-      end: VISIBLE_DISABLED,
-    };
+    return withWxAppTelephonyControls(
+      {
+        ...getDefaultInteractionUIControls(),
+        hold: VISIBLE_ENABLED,
+        transfer: VISIBLE_ENABLED,
+        consult: VISIBLE_ENABLED,
+        recording: recordingControl,
+        end: VISIBLE_DISABLED,
+      },
+      isWxAppEngaged,
+      currentLeg,
+      isWrappingUp
+    );
   }
 
   if (isConsultRequestedPhase && !isEpDnPendingConferenceMergeUi) {
     if (currentLeg === 'main') {
-      return {
-        ...getDefaultInteractionUIControls(),
-        transfer: shouldHideBlindTransferForEpDnPendingConferenceMerge
-          ? DISABLED
-          : VISIBLE_DISABLED,
-        conference: VISIBLE_DISABLED,
-        end: VISIBLE_DISABLED,
-      };
+      return withWxAppTelephonyControls(
+        {
+          ...getDefaultInteractionUIControls(),
+          transfer: shouldHideBlindTransferForEpDnPendingConferenceMerge
+            ? DISABLED
+            : VISIBLE_DISABLED,
+          conference: VISIBLE_DISABLED,
+          end: VISIBLE_DISABLED,
+        },
+        isWxAppEngaged,
+        currentLeg,
+        isWrappingUp
+      );
     }
 
     if (currentLeg === 'consult') {
-      return {
-        ...getDefaultInteractionUIControls(),
-        endConsult: VISIBLE_ENABLED,
-        switch: VISIBLE_DISABLED,
-        transfer: VISIBLE_DISABLED,
-        transferConference: inConference ? VISIBLE_DISABLED : DISABLED,
-        mergeToConference: VISIBLE_DISABLED,
-      };
+      return withWxAppTelephonyControls(
+        {
+          ...getDefaultInteractionUIControls(),
+          endConsult: VISIBLE_ENABLED,
+          switch: VISIBLE_DISABLED,
+          transfer: VISIBLE_DISABLED,
+          transferConference: inConference ? VISIBLE_DISABLED : DISABLED,
+          mergeToConference: VISIBLE_DISABLED,
+        },
+        isWxAppEngaged,
+        currentLeg,
+        isWrappingUp
+      );
     }
   }
 
@@ -415,11 +535,24 @@ function computeVoiceInteractionUIControls(
     // Desktop/WebRTC + inbound: accept enabled (agent manually accepts)
     // Desktop/WebRTC + outdial: accept disabled (auto-answer handles it; Widgets show "Accept" disabled)
     // Extension mode (non-WebRTC): accept disabled (Widgets show "Ringing...")
-    accept:
-      state === TaskState.OFFERED && !interaction?.isTerminated
-        ? {isVisible: true, isEnabled: isWebrtc && !isOutdial}
-        : DISABLED,
+    accept: (() => {
+      if (isWxAppInboundOffer) {
+        return wxAppAcceptInFlight || wxAppAnswerPending ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+      }
+      if (isWxAppOutdialOffer) {
+        return wxAppAcceptInFlight || wxAppAnswerPending ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+      }
+      if (state === TaskState.OFFERED && !interaction?.isTerminated) {
+        return {isVisible: true, isEnabled: isWebrtc && !isOutdial};
+      }
+
+      return DISABLED;
+    })(),
     decline: (() => {
+      if (wxAppAcceptInFlight) return VISIBLE_DISABLED;
+      if (wxAppAnswerPending && isWxAppInboundOffer) return VISIBLE_DISABLED;
+      if (isWxAppInboundOffer) return VISIBLE_ENABLED;
+      if (isWxAppOutdialOffer) return VISIBLE_ENABLED;
       if (!isWebrtc || state !== TaskState.OFFERED || interaction?.isTerminated) return DISABLED;
 
       return isOutdial ? VISIBLE_DISABLED : VISIBLE_ENABLED;
@@ -447,8 +580,11 @@ function computeVoiceInteractionUIControls(
       return canHold ? VISIBLE_ENABLED : VISIBLE_DISABLED;
     })(),
 
-    // Mute: WebRTC only, active calls; hidden entirely during wrapup
+    // Mute: WebRTC or wxApp engaged calls; hidden entirely during wrapup
     mute: (() => {
+      if (isWxAppEngaged && !isWrappingUp) {
+        return currentLeg === 'main' ? VISIBLE_ENABLED : DISABLED;
+      }
       if (!isWebrtc) return DISABLED;
       if (isWrappingUp) return DISABLED;
       if (isEpDnPostCallCustomerLeft && inConference) return VISIBLE_DISABLED;
@@ -712,6 +848,14 @@ function computeVoiceInteractionUIControls(
 
       return DISABLED;
     })(),
+
+    keypad: (() => {
+      if (isWxAppEngaged && !isWrappingUp) {
+        return currentLeg === 'main' ? VISIBLE_ENABLED : DISABLED;
+      }
+
+      return DISABLED;
+    })(),
   };
 }
 
@@ -743,6 +887,7 @@ function computeDigitalInteractionUIControls(
     transferConference: DISABLED,
     mergeToConference: DISABLED,
     switch: DISABLED,
+    keypad: DISABLED,
   };
 }
 
@@ -896,6 +1041,11 @@ export function computeUIControls(
     return getDefaultUIControls();
   }
 
+  const consultTransferDestinations = getConsultTransferDestinations(
+    context.uiControlConfig,
+    fallbackTaskData ?? context.taskData
+  );
+
   switch (context.uiControlConfig.channelType) {
     case TASK_CHANNEL_TYPE.VOICE: {
       const {hasConsultLeg, activeLeg, mainState, consultState} = getVoiceLegState(
@@ -922,13 +1072,19 @@ export function computeUIControls(
           )
         : getDefaultInteractionUIControls();
 
-      return createTaskUIControls(mainControls, consultControls, activeLeg);
+      return createTaskUIControls(
+        mainControls,
+        consultControls,
+        activeLeg,
+        consultTransferDestinations
+      );
     }
     case TASK_CHANNEL_TYPE.DIGITAL:
       return createTaskUIControls(
         computeDigitalInteractionUIControls(currentState, context, fallbackTaskData),
         getDefaultInteractionUIControls(),
-        'main'
+        'main',
+        consultTransferDestinations
       );
     default:
       return getDefaultUIControls();
@@ -947,6 +1103,16 @@ function haveInteractionUIControlsChanged(
   });
 }
 
+function haveDestinationListChanged(
+  previous: DestinationControls['consult'],
+  next: DestinationControls['consult']
+): boolean {
+  return (
+    previous.length !== next.length ||
+    previous.some((destination, index) => destination !== next[index])
+  );
+}
+
 export function haveUIControlsChanged(
   previous: TaskUIControls | undefined,
   next: TaskUIControls
@@ -955,6 +1121,14 @@ export function haveUIControlsChanged(
 
   return (
     previous.activeLeg !== next.activeLeg ||
+    haveDestinationListChanged(
+      previous.consultTransferDestinations.consult,
+      next.consultTransferDestinations.consult
+    ) ||
+    haveDestinationListChanged(
+      previous.consultTransferDestinations.transfer,
+      next.consultTransferDestinations.transfer
+    ) ||
     haveInteractionUIControlsChanged(previous.main, next.main) ||
     haveInteractionUIControlsChanged(previous.consult, next.consult)
   );

package/src/services/task/types.ts

@@ -3,6 +3,7 @@ import type {AnyActorRef} from 'xstate';
 import {TaskEventPayload} from './state-machine';
 import {Msg} from '../core/GlobalTypes';
 import AutoWrapup from './AutoWrapup';
+import type {CollaborationAccess} from '../config/types';
 
 /**
  * Unique identifier for a task in the contact center system
@@ -33,7 +34,7 @@ export const DESTINATION_TYPE = {
   DIALNUMBER: 'dialNumber',
   /** Route task to a specific agent */
   AGENT: 'agent',
-  /** Route task to an entry point (supported only for consult operations) */
+  /** Route task to an entry point */
   ENTRYPOINT: 'entryPoint',
 };
 
@@ -67,6 +68,17 @@ export const CONSULT_TRANSFER_DESTINATION_TYPE = {
  */
 export type ConsultTransferDestinationType = Enum<typeof CONSULT_TRANSFER_DESTINATION_TYPE>;
 
+/**
+ * Agent-profile policy used by the task state machine to derive consult/transfer destinations.
+ * @internal
+ */
+export type ConsultTransferDestinationConfig = {
+  allowConsultToQueue: boolean;
+  accessQueue?: CollaborationAccess;
+  accessEntryPoint?: CollaborationAccess;
+  accessBuddyTeam?: CollaborationAccess;
+};
+
 /**
  * Defines all supported media channel types for customer interactions
  * These represent the different ways customers can communicate with agents
@@ -234,6 +246,11 @@ export enum TASK_EVENTS {
    */
   TASK_UI_CONTROLS_UPDATED = 'task:ui-controls-updated',
 
+  /**
+   * Triggered when wxApp mute state changes from Webex App (Mercury sync or call details).
+   */
+  TASK_WXAPP_MUTE_STATE_UPDATED = 'task:wxapp-mute-state-updated',
+
   /**
    * Triggered when a consultation request is accepted
    * @example
@@ -1134,6 +1151,8 @@ export type TaskData = {
   reservedAgentChannelId?: string;
   /** Indicates if wrap-up is required for this task */
   wrapUpRequired?: boolean;
+  /** SDK-internal: skip task:outdialFailed when non-wxApp agent-terminated outdial still needs wrapup */
+  suppressOutdialFailedPopup?: boolean;
 
   /**
    * Current consultation status derived from state machine
@@ -1215,6 +1234,19 @@ export type InteractionUIControls = {
   mergeToConference: TaskUIControlState;
   wrapup: TaskUIControlState;
   switch: TaskUIControlState;
+  keypad?: TaskUIControlState;
+};
+
+/** Options for {@link ITask.toggleMute} — wxApp engaged calls use `muted` for target state. */
+export type TaskToggleMuteOptions = {
+  muted?: boolean;
+  lineOwnerId?: string;
+};
+
+/** Options for {@link ITask.transmitDtmf} — wxApp engaged in-call DTMF. */
+export type TaskTransmitDtmfOptions = {
+  dtmf: string;
+  lineOwnerId?: string;
 };
 
 export type TaskUILeg = 'main' | 'consult';
@@ -1228,6 +1260,14 @@ export type TaskUIControls = {
   main: InteractionUIControls;
   consult: InteractionUIControls;
   activeLeg: TaskUILeg;
+  /**
+   * Ordered destination categories available for each action.
+   * The first category is the default for consumers that render a destination picker.
+   */
+  consultTransferDestinations: {
+    consult: ConsultTransferDestinationType[];
+    transfer: ConsultTransferDestinationType[];
+  };
 };
 
 /**
@@ -1629,6 +1669,15 @@ export type ParticipantBooleanKey =
  */
 export type TaskResponse = AgentContact | Error | void;
 
+/**
+ * Request payload for removing a supported participant from an active conference.
+ * @public
+ */
+export type DropConferenceParticipantPayload = {
+  /** Participant identifier supplied by the current task roster. */
+  participantId: string;
+};
+
 /**
  * Payload shape used by consult conference helper utilities.
  */
@@ -1687,6 +1736,29 @@ export interface ITask extends IEventEmitter {
    */
   readonly uiControls: TaskUIControls;
 
+  /**
+   * Update wxApp thick-client answer flag at runtime.
+   * Voice tasks override to refresh uiControls; other channel types no-op.
+   * @internal
+   */
+  setEnableWxBetterTogether(enabled: boolean): void;
+
+  /**
+   * Apply wxApp mute state from Mercury sync or call-details fetch.
+   * @internal
+   */
+  applyWxAppMuteStateFromSync(incomingCallId: string, muted: boolean): void;
+
+  /**
+   * Current wxApp mute state for engaged telephony (Voice tasks only).
+   */
+  getWxAppMuted?(): boolean;
+
+  /**
+   * Re-seed wxApp mute from GET telephony/calls/{callId}. Resolves to muted state when known.
+   */
+  syncWxAppMuteFromCallDetails?(): Promise<boolean | undefined>;
+
   /**
    * State machine instance for managing task state transitions and derived properties.
    * The state machine handles:
@@ -1875,6 +1947,18 @@ export interface ITask extends IEventEmitter {
    */
   consultConference(): Promise<TaskResponse>;
 
+  /**
+   * Removes a supported participant from the active conference.
+   * Resolves after the correlated ParticipantLeftConference routing event.
+   * @param payload - Participant identifier to remove
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.dropConferenceParticipant({participantId: 'participant-id'});
+   * ```
+   */
+  dropConferenceParticipant(payload: DropConferenceParticipantPayload): Promise<TaskResponse>;
+
   /**
    * Exits from an ongoing conference.
    * @returns Promise<TaskResponse>
@@ -1909,14 +1993,29 @@ export interface ITask extends IEventEmitter {
   switchCall(): Promise<TaskResponse>;
 
   /**
-   * Toggles mute/unmute for the local audio stream during a WebRTC task.
+   * Toggles mute/unmute for the active call.
+   * WebRTC tasks toggle the local stream; wxApp engaged tasks route to telephony mute REST when
+   * `enableWxBetterTogether` is active.
+   * @param options - Optional target mute state (`muted`) for wxApp; ignored for WebRTC toggle.
    * @returns Promise<void>
    * @example
    * ```typescript
    * await task.toggleMute();
+   * await task.toggleMute({ muted: true });
+   * ```
+   */
+  toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
+
+  /**
+   * Sends in-call DTMF tones for wxApp engaged telephony tasks when `enableWxBetterTogether` is active.
+   * @param options - DTMF digit(s) and optional shared-line owner id.
+   * @returns Promise<void>
+   * @example
+   * ```typescript
+   * await task.transmitDtmf({ dtmf: '5' });
    * ```
    */
-  toggleMute(): Promise<void>;
+  transmitDtmf(options: TaskTransmitDtmfOptions): Promise<void>;
 }
 
 /**
@@ -1952,6 +2051,12 @@ export interface IVoice extends ITask {
    * ```
    */
   holdResume(): Promise<TaskResponse>;
+  /** @see wxAppVoiceMethods — WXCC-6026 */
+  isWebexAppCallingOffer(): boolean;
+  /** @see wxAppVoiceMethods — WXCC-6026 */
+  getCallingDeviceDetails(): import('./WebexCallingUtils').WebexCallingDeviceDetails | undefined;
+  /** @see wxAppVoiceMethods — WXCC-6026 */
+  getWebexCallingCallId(): string | null;
 }
 
 /**
@@ -1962,6 +2067,9 @@ export type VoiceUIControlOptions = {
   isEndConsultEnabled?: boolean;
   voiceVariant?: VoiceVariant;
   isRecordingEnabled?: boolean;
+  enableWxBetterTogether?: boolean;
+  consultTransferConfig?: ConsultTransferDestinationConfig;
+  answerCallOnWebexService?: import('../AnswerCallOnWebexService').default;
 };
 
 /**
@@ -1987,7 +2095,7 @@ export interface IWebRTC extends IVoice {
    * task.toggleMute();
    * ```
    */
-  toggleMute(): Promise<void>;
+  toggleMute(options?: TaskToggleMuteOptions): Promise<void>;
   /**
    * Decline the incoming task for Browser Login
    *
@@ -2012,6 +2120,8 @@ export type WebSocketPayload = TaskData & {
   type: string;
   mediaResourceId?: string;
   reason?: string;
+  /** ContactEnded: party that ended the contact (e.g. 'Agent', 'Customer') */
+  terminatingParty?: string;
   /**
    * Optional real-time transcript chunk payload.
    * Present on REAL_TIME_TRANSCRIPTION notifications.