@webex/contact-center 3.9.0-next.9 → 3.10.0

package/src/services/task/index.ts

@@ -5,11 +5,12 @@ import {
   generateTaskErrorObject,
   deriveConsultTransferDestinationType,
   getDestinationAgentId,
+  buildConsultConferenceParamData,
 } from '../core/Utils';
 import {Failure} from '../core/GlobalTypes';
 import {LoginOption} from '../../types';
 import {TASK_FILE} from '../../constants';
-import {METHODS} from './constants';
+import {METHODS, KEYS_TO_NOT_DELETE} from './constants';
 import routingContact from './contact';
 import LoggerProxy from '../../logger-proxy';
 import {
@@ -138,6 +139,7 @@ export default class Task extends EventEmitter implements ITask {
   public webCallMap: Record<TaskId, CallId>;
   private wrapupData: WrapupData;
   public autoWrapup?: AutoWrapup;
+  private agentId: string;
 
   /**
    * Creates a new Task instance which provides the following features:
@@ -150,7 +152,8 @@ export default class Task extends EventEmitter implements ITask {
     contact: ReturnType<typeof routingContact>,
     webCallingService: WebCallingService,
     data: TaskData,
-    wrapupData: WrapupData
+    wrapupData: WrapupData,
+    agentId: string
   ) {
     super();
     this.contact = contact;
@@ -161,6 +164,7 @@ export default class Task extends EventEmitter implements ITask {
     this.metricsManager = MetricsManager.getInstance();
     this.registerWebCallListeners();
     this.setupAutoWrapupTimer();
+    this.agentId = agentId;
   }
 
   /**
@@ -277,9 +281,24 @@ export default class Task extends EventEmitter implements ITask {
    * @private
    */
   private reconcileData(oldData: TaskData, newData: TaskData): TaskData {
+    // Remove keys from oldData that are not in newData
+    Object.keys(oldData).forEach((key) => {
+      if (!(key in newData) && !KEYS_TO_NOT_DELETE.includes(key as string)) {
+        delete oldData[key];
+      }
+    });
+
+    // Merge or update keys from newData
     Object.keys(newData).forEach((key) => {
-      if (newData[key] && typeof newData[key] === 'object' && !Array.isArray(newData[key])) {
-        oldData[key] = this.reconcileData({...oldData[key]}, newData[key]);
+      if (
+        newData[key] &&
+        typeof newData[key] === 'object' &&
+        !Array.isArray(newData[key]) &&
+        oldData[key] &&
+        typeof oldData[key] === 'object' &&
+        !Array.isArray(oldData[key])
+      ) {
+        this.reconcileData(oldData[key], newData[key]);
       } else {
         oldData[key] = newData[key];
       }
@@ -1488,4 +1507,281 @@ export default class Task extends EventEmitter implements ITask {
       throw err;
     }
   }
+
+  /**
+   * Starts a consultation conference by merging the consultation call with the main call
+   *
+   * Creates a three-way conference between the agent, customer, and consulted party
+   * Extracts required consultation data from the current task data
+   * On success, emits a `task:conferenceStarted` event
+   *
+   * @returns Promise<TaskResponse> - Response from the consultation conference API
+   * @throws Error if the operation fails or if consultation data is invalid
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await task.consultConference();
+   *   console.log('Conference started successfully');
+   * } catch (error) {
+   *   console.error('Failed to start conference:', error);
+   * }
+   * ```
+   */
+  public async consultConference(): Promise<TaskResponse> {
+    // Extract consultation conference data from task data (used in both try and catch)
+    const consultationData = {
+      agentId: this.agentId,
+      destAgentId: this.data.destAgentId,
+      destinationType: this.data.destinationType || 'agent',
+    };
+
+    try {
+      LoggerProxy.info(`Initiating consult conference to ${consultationData.destAgentId}`, {
+        module: TASK_FILE,
+        method: METHODS.CONSULT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      const paramsDataForConferenceV2 = buildConsultConferenceParamData(
+        consultationData,
+        this.data.interactionId
+      );
+
+      const response = await this.contact.consultConference({
+        interactionId: paramsDataForConferenceV2.interactionId,
+        data: paramsDataForConferenceV2.data,
+      });
+
+      // Track success metrics (following consultTransfer pattern)
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_START_SUCCESS,
+        {
+          taskId: this.data.interactionId,
+          destination: paramsDataForConferenceV2.data.to,
+          destinationType: paramsDataForConferenceV2.data.destinationType,
+          agentId: paramsDataForConferenceV2.data.agentId,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.log(`Consult conference started successfully`, {
+        module: TASK_FILE,
+        method: METHODS.CONSULT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      return response;
+    } catch (error) {
+      const err = generateTaskErrorObject(error, METHODS.CONSULT_CONFERENCE, TASK_FILE);
+      const taskErrorProps = {
+        trackingId: err.data?.trackingId,
+        errorMessage: err.data?.message,
+        errorType: err.data?.errorType,
+        errorData: err.data?.errorData,
+        reasonCode: err.data?.reasonCode,
+      };
+
+      // Track failure metrics (following consultTransfer pattern)
+      // Build conference data for error tracking using extracted data
+      const failedParamsData = buildConsultConferenceParamData(
+        consultationData,
+        this.data.interactionId
+      );
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_START_FAILED,
+        {
+          taskId: this.data.interactionId,
+          destination: failedParamsData.data.to,
+          destinationType: failedParamsData.data.destinationType,
+          agentId: failedParamsData.data.agentId,
+          error: error.toString(),
+          ...taskErrorProps,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error.details || {}),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.error(`Failed to start consult conference`, {
+        module: TASK_FILE,
+        method: METHODS.CONSULT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      throw err;
+    }
+  }
+
+  /**
+   * Exits the current conference by removing the agent from the conference call
+   *
+   * Exits the agent from the conference, leaving the customer and consulted party connected
+   * On success, emits a `task:conferenceEnded` event
+   *
+   * @returns Promise<TaskResponse> - Response from the conference exit API
+   * @throws Error if the operation fails or if no active conference exists
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await task.exitConference();
+   *   console.log('Successfully exited conference');
+   * } catch (error) {
+   *   console.error('Failed to exit conference:', error);
+   * }
+   * ```
+   */
+  public async exitConference(): Promise<TaskResponse> {
+    try {
+      LoggerProxy.info(`Exiting consult conference`, {
+        module: TASK_FILE,
+        method: METHODS.EXIT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      // Validate that interaction ID exists
+      if (!this.data.interactionId) {
+        throw new Error('Invalid interaction ID');
+      }
+
+      const response = await this.contact.exitConference({
+        interactionId: this.data.interactionId,
+      });
+
+      // Track success metrics (following consultTransfer pattern)
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_END_SUCCESS,
+        {
+          taskId: this.data.interactionId,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.log(`Consult conference exited successfully`, {
+        module: TASK_FILE,
+        method: METHODS.EXIT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      return response;
+    } catch (error) {
+      const err = generateTaskErrorObject(error, METHODS.EXIT_CONFERENCE, TASK_FILE);
+      const taskErrorProps = {
+        trackingId: err.data?.trackingId,
+        errorMessage: err.data?.message,
+        errorType: err.data?.errorType,
+        errorData: err.data?.errorData,
+        reasonCode: err.data?.reasonCode,
+      };
+
+      // Track failure metrics (following consultTransfer pattern)
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_END_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...taskErrorProps,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error.details || {}),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.error(`Failed to exit consult conference`, {
+        module: TASK_FILE,
+        method: METHODS.EXIT_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      throw err;
+    }
+  }
+
+  /**
+   * Transfers the current conference to another agent
+   *
+   * Moves the entire conference (including all participants) to a new agent,
+   * while the current agent exits and goes to wrapup
+   * On success, the current agent receives `task:conferenceEnded` event
+   *
+   * @returns Promise<TaskResponse> - Response from the conference transfer API
+   * @throws Error if the operation fails or if no active conference exists
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await task.transferConference();
+   *   console.log('Conference transferred successfully');
+   * } catch (error) {
+   *   console.error('Failed to transfer conference:', error);
+   * }
+   * ```
+   */
+  public async transferConference(): Promise<TaskResponse> {
+    try {
+      LoggerProxy.info(`Transferring conference`, {
+        module: TASK_FILE,
+        method: METHODS.TRANSFER_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      // Validate that interaction ID exists
+      if (!this.data.interactionId) {
+        throw new Error('Invalid interaction ID');
+      }
+
+      const response = await this.contact.conferenceTransfer({
+        interactionId: this.data.interactionId,
+      });
+
+      // Track success metrics (following consultTransfer pattern)
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_TRANSFER_SUCCESS,
+        {
+          taskId: this.data.interactionId,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.log(`Conference transferred successfully`, {
+        module: TASK_FILE,
+        method: METHODS.TRANSFER_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      return response;
+    } catch (error) {
+      const err = generateTaskErrorObject(error, METHODS.TRANSFER_CONFERENCE, TASK_FILE);
+      const taskErrorProps = {
+        trackingId: err.data?.trackingId,
+        errorMessage: err.data?.message,
+        errorType: err.data?.errorType,
+        errorData: err.data?.errorData,
+        reasonCode: err.data?.reasonCode,
+      };
+
+      // Track failure metrics (following consultTransfer pattern)
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_CONFERENCE_TRANSFER_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...taskErrorProps,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error.details || {}),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      LoggerProxy.error(`Failed to transfer conference`, {
+        module: TASK_FILE,
+        method: METHODS.TRANSFER_CONFERENCE,
+        interactionId: this.data.interactionId,
+      });
+
+      throw err;
+    }
+  }
 }

package/src/services/task/types.ts

@@ -370,6 +370,126 @@ export enum TASK_EVENTS {
    * ```
    */
   TASK_OFFER_CONTACT = 'task:offerContact',
+
+  /**
+   * Triggered when a conference is being established
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_ESTABLISHING, (task: ITask) => {
+   *   console.log('Conference establishing:', task.data.interactionId);
+   *   // Handle conference setup in progress
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_ESTABLISHING = 'task:conferenceEstablishing',
+
+  /**
+   * Triggered when a conference is started successfully
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_STARTED, (task: ITask) => {
+   *   console.log('Conference started:', task.data.interactionId);
+   *   // Handle conference start
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_STARTED = 'task:conferenceStarted',
+
+  /**
+   * Triggered when a conference fails to start
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_FAILED, (task: ITask) => {
+   *   console.log('Conference failed:', task.data.interactionId);
+   *   // Handle conference failure
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_FAILED = 'task:conferenceFailed',
+
+  /**
+   * Triggered when a conference is ended successfully
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_ENDED, (task: ITask) => {
+   *   console.log('Conference ended:', task.data.interactionId);
+   *   // Handle conference end
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_ENDED = 'task:conferenceEnded',
+
+  /**
+   * Triggered when a participant joins the conference
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_PARTICIPANT_JOINED, (task: ITask) => {
+   *   console.log('Participant joined conference:', task.data.interactionId);
+   *   // Handle participant joining
+   * });
+   * ```
+   */
+  TASK_PARTICIPANT_JOINED = 'task:participantJoined',
+
+  /**
+   * Triggered when a participant leaves the conference
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_PARTICIPANT_LEFT, (task: ITask) => {
+   *   console.log('Participant left conference:', task.data.interactionId);
+   *   // Handle participant leaving
+   * });
+   * ```
+   */
+  TASK_PARTICIPANT_LEFT = 'task:participantLeft',
+
+  /**
+   * Triggered when conference transfer is successful
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_TRANSFERRED, (task: ITask) => {
+   *   console.log('Conference transferred:', task.data.interactionId);
+   *   // Handle successful conference transfer
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_TRANSFERRED = 'task:conferenceTransferred',
+
+  /**
+   * Triggered when conference transfer fails
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_TRANSFER_FAILED, (task: ITask) => {
+   *   console.log('Conference transfer failed:', task.data.interactionId);
+   *   // Handle failed conference transfer
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_TRANSFER_FAILED = 'task:conferenceTransferFailed',
+
+  /**
+   * Triggered when ending a conference fails
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_CONFERENCE_END_FAILED, (task: ITask) => {
+   *   console.log('Conference end failed:', task.data.interactionId);
+   *   // Handle failed conference end
+   * });
+   * ```
+   */
+  TASK_CONFERENCE_END_FAILED = 'task:conferenceEndFailed',
+
+  /**
+   * Triggered when participant exit from conference fails
+   * @example
+   * ```typescript
+   * task.on(TASK_EVENTS.TASK_PARTICIPANT_LEFT_FAILED, (task: ITask) => {
+   *   console.log('Participant failed to leave conference:', task.data.interactionId);
+   *   // Handle failed participant exit
+   * });
+   * ```
+   */
+  TASK_PARTICIPANT_LEFT_FAILED = 'task:participantLeftFailed',
 }
 
 /**
@@ -613,6 +733,8 @@ export type TaskData = {
   isConsulted?: boolean;
   /** Indicates if the task is in conference state */
   isConferencing: boolean;
+  /** Indicates if a conference is currently in progress (2+ active agents) */
+  isConferenceInProgress?: boolean;
   /** Identifier of agent who last updated the task */
   updatedBy?: string;
   /** Type of destination for transfer/consult */
@@ -883,6 +1005,19 @@ export type ConsultConferenceData = {
   destinationType: string;
 };
 
+/**
+ * Legacy consultation conference data type matching Agent Desktop
+ * @public
+ */
+export type consultConferencePayloadData = {
+  /** Identifier of the agent initiating consult/conference */
+  agentId: string;
+  /** Type of destination (e.g., 'agent', 'queue') */
+  destinationType: string;
+  /** Identifier of the destination agent */
+  destAgentId: string;
+};
+
 /**
  * Parameters required for cancelling a consult to queue operation
  * @public
@@ -931,6 +1066,8 @@ export type DialerPayload = {
   mediaType: 'telephony' | 'chat' | 'social' | 'email';
   /** The outbound type for the task */
   outboundType: 'OUTDIAL' | 'CALLBACK' | 'EXECUTE_FLOW';
+  /** The Outdial ANI number that will be used while making a call to the customer.  */
+  origin: string;
 };
 
 /**
@@ -1000,16 +1137,16 @@ export interface ITask extends EventEmitter {
   autoWrapup?: AutoWrapup;
 
   /**
-   * cancels the auto-wrapup timer for the task
-   * This method stops the auto-wrapup process if it is currently active
+   * Cancels the auto-wrapup timer for the task.
+   * This method stops the auto-wrapup process if it is currently active.
    * Note: This is supported only in single session mode. Not supported in multi-session mode.
    * @returns void
    */
   cancelAutoWrapupTimer(): void;
 
   /**
-   * Deregisters all web call event listeners
-   * Used when cleaning up task resources
+   * Deregisters all web call event listeners.
+   * Used when cleaning up task resources.
    * @ignore
    */
   unregisterWebCallListeners(): void;
@@ -1029,7 +1166,7 @@ export interface ITask extends EventEmitter {
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.accept();
+   * await task.accept();
    * ```
    */
   accept(): Promise<TaskResponse>;
@@ -1039,48 +1176,48 @@ export interface ITask extends EventEmitter {
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.decline();
+   * await task.decline();
    * ```
    */
   decline(): Promise<TaskResponse>;
 
   /**
-   * Places the current task on hold
+   * Places the current task on hold.
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.hold();
+   * await task.hold();
    * ```
    */
   hold(): Promise<TaskResponse>;
 
   /**
-   * Resumes a task that was previously on hold
+   * Resumes a task that was previously on hold.
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.resume();
+   * await task.resume();
    * ```
    */
   resume(): Promise<TaskResponse>;
 
   /**
-   * Ends/terminates the current task
+   * Ends/terminates the current task.
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.end();
+   * await task.end();
    * ```
    */
   end(): Promise<TaskResponse>;
 
   /**
-   * Initiates wrap-up process for the task with specified details
+   * Initiates wrap-up process for the task with specified details.
    * @param wrapupPayload - Wrap-up details including reason and auxiliary code
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.wrapup({
+   * await task.wrapup({
    *   wrapUpReason: "Customer issue resolved",
    *   auxCodeId: "RESOLVED"
    * });
@@ -1089,25 +1226,109 @@ export interface ITask extends EventEmitter {
   wrapup(wrapupPayload: WrapupPayLoad): Promise<TaskResponse>;
 
   /**
-   * Pauses the recording for current task
+   * Pauses the recording for current task.
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.pauseRecording();
+   * await task.pauseRecording();
    * ```
    */
   pauseRecording(): Promise<TaskResponse>;
 
   /**
-   * Resumes a previously paused recording
+   * Resumes a previously paused recording.
    * @param resumeRecordingPayload - Parameters for resuming the recording
    * @returns Promise<TaskResponse>
    * @example
    * ```typescript
-   * task.resumeRecording({
+   * await task.resumeRecording({
    *   autoResumed: false
    * });
    * ```
    */
   resumeRecording(resumeRecordingPayload: ResumeRecordingPayload): Promise<TaskResponse>;
+
+  /**
+   * Initiates a consultation with another agent or queue.
+   * @param consultPayload - Consultation details including destination and type
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.consult({ to: "agentId", destinationType: "agent" });
+   * ```
+   */
+  consult(consultPayload: ConsultPayload): Promise<TaskResponse>;
+
+  /**
+   * Ends an ongoing consultation.
+   * @param consultEndPayload - Details for ending the consultation
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.endConsult({ isConsult: true, taskId: "taskId" });
+   * ```
+   */
+  endConsult(consultEndPayload: ConsultEndPayload): Promise<TaskResponse>;
+
+  /**
+   * Transfers the task to another agent or queue.
+   * @param transferPayload - Transfer details including destination and type
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.transfer({ to: "queueId", destinationType: "queue" });
+   * ```
+   */
+  transfer(transferPayload: TransferPayLoad): Promise<TaskResponse>;
+
+  /**
+   * Transfers the task after consultation.
+   * @param consultTransferPayload - Details for consult transfer (optional)
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.consultTransfer({ to: "agentId", destinationType: "agent" });
+   * ```
+   */
+  consultTransfer(consultTransferPayload?: ConsultTransferPayLoad): Promise<TaskResponse>;
+
+  /**
+   * Initiates a consult conference (merge consult call with main call).
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.consultConference();
+   * ```
+   */
+  consultConference(): Promise<TaskResponse>;
+
+  /**
+   * Exits from an ongoing conference.
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.exitConference();
+   * ```
+   */
+  exitConference(): Promise<TaskResponse>;
+
+  /**
+   * Transfers the conference to another participant.
+   * @returns Promise<TaskResponse>
+   * @example
+   * ```typescript
+   * await task.transferConference();
+   * ```
+   */
+  transferConference(): Promise<TaskResponse>;
+
+  /**
+   * Toggles mute/unmute for the local audio stream during a WebRTC task.
+   * @returns Promise<void>
+   * @example
+   * ```typescript
+   * await task.toggleMute();
+   * ```
+   */
+  toggleMute(): Promise<void>;
 }