@webex/contact-center 3.12.0-task-refactor.8 → 3.12.0-task-refactor.10

package/src/cc.ts

@@ -736,11 +736,13 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
           this.taskManager.setWebRtcEnabled(this.agentConfig.webRtcEnabled);
           this.apiAIAssistant.setAIFeatureFlags(this.agentConfig.aiFeature);
           /**
-           * TODO: We need to re-check this condition if this websocket is only for realtime transcripts
-           * or other AI Assistant features will also use the same.
-           * If the latter is true, we need to update this condition.
+           * RTD websocket currently supports realtime transcripts and suggested responses.
+           * Extend this condition when additional AI RTD features are introduced.
            */
-          if (this.agentConfig.aiFeature?.realtimeTranscripts?.enable) {
+          if (
+            this.agentConfig.aiFeature?.realtimeTranscripts?.enable ||
+            this.agentConfig.aiFeature?.suggestedResponses?.enable
+          ) {
             LoggerProxy.info('Connecting to RTD websocket', {
               module: CC_FILE,
               method: METHODS.CONNECT_WEBSOCKET,

package/src/constants.ts

@@ -63,5 +63,6 @@ export const METHODS = {
   GET_OUTDIAL_ANI_ENTRIES: 'getOutdialAniEntries',
   GET_BASE_URL: 'getBaseUrl',
   SEND_EVENT: 'sendEvent',
+  GET_SUGGESTED_RESPONSE: 'getSuggestedResponse',
   FETCH_HISTORIC_TRANSCRIPTS: 'fetchHistoricTranscripts',
 };

package/src/metrics/constants.ts

@@ -166,6 +166,8 @@ export const METRIC_EVENT_NAMES = {
   // AI Assistant events
   AI_ASSISTANT_SEND_EVENT_SUCCESS: 'AI Assistant Send Event Success',
   AI_ASSISTANT_SEND_EVENT_FAILED: 'AI Assistant Send Event Failed',
+  AI_ASSISTANT_GET_SUGGESTED_RESPONSE_SUCCESS: 'AI Assistant Get Suggested Response Success',
+  AI_ASSISTANT_GET_SUGGESTED_RESPONSE_FAILED: 'AI Assistant Get Suggested Response Failed',
   AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS:
     'AI Assistant Fetch Historic Transcripts Success',
   AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED: 'AI Assistant Fetch Historic Transcripts Failed',

package/src/services/ApiAiAssistant.ts

@@ -1,3 +1,4 @@
+import {v4 as uuidv4} from 'uuid';
 import LoggerProxy from '../logger-proxy';
 import MetricsManager from '../metrics/MetricsManager';
 import {METRIC_EVENT_NAMES} from '../metrics/constants';
@@ -10,6 +11,7 @@ import {
   AIAssistantEventType,
   AIAssistantEventName,
   HistoricTranscriptsResponse,
+  SuggestedResponseParams,
 } from '../types';
 import {getErrorDetails} from './core/Utils';
 import {
@@ -83,13 +85,16 @@ export class ApiAIAssistant {
     interactionId: string,
     eventType: AIAssistantEventType,
     eventName: AIAssistantEventName,
-    action: TranscriptAction
+    action?: TranscriptAction,
+    context?: string,
+    languageCode?: string,
+    trackingId?: string
   ): Promise<Record<string, unknown>> {
     LoggerProxy.info('Sending event', {
       module: CC_FILE,
       method: METHODS.SEND_EVENT,
       interactionId,
-      data: {eventType, eventName, action},
+      data: {eventType, eventName, action, context},
     });
     this.metricsManager.timeEvent([
       METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_EVENT_SUCCESS,
@@ -112,7 +117,10 @@ export class ApiAIAssistant {
             data: {
               interactionId,
               action,
+              context,
               actionTimeStamp: String(Date.now()),
+              languageCode,
+              trackingId,
             },
           },
         },
@@ -143,6 +151,98 @@ export class ApiAIAssistant {
     }
   }
 
+  /**
+   * Requests a suggested response for an interaction.
+   *
+   * @param params - Suggestion request parameters
+   * @returns HTTP response body from the AI Assistant event API
+   * @public
+   */
+  public async getSuggestedResponse(params: SuggestedResponseParams): Promise<any> {
+    const {agentId, interactionId, context} = params;
+    const trimmedContext = context?.trim();
+    const languageCode = params.languageCode ?? 'en';
+    const trackingId = `WX_CC_SDK_${uuidv4()}`;
+    const eventName = trimmedContext
+      ? AIAssistantEventName.ADD_SUGGESTIONS_EXTRA_CONTEXT
+      : AIAssistantEventName.GET_SUGGESTIONS;
+
+    const loggerContext = {
+      module: CC_FILE,
+      method: METHODS.GET_SUGGESTED_RESPONSE,
+      interactionId,
+      trackingId,
+      data: {eventName},
+    };
+
+    LoggerProxy.info('Requesting suggested response', loggerContext);
+
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_GET_SUGGESTED_RESPONSE_SUCCESS,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_GET_SUGGESTED_RESPONSE_FAILED,
+    ]);
+
+    try {
+      if (!this.aiFeature?.suggestedResponses?.enable) {
+        const {error: detailedError} = getErrorDetails(
+          new Error('SUGGESTED_RESPONSES_NOT_ENABLED'),
+          METHODS.GET_SUGGESTED_RESPONSE,
+          CC_FILE
+        );
+        throw detailedError;
+      }
+
+      const orgId = this.webex.credentials.getOrgId();
+
+      const response = await this.sendEvent(
+        agentId,
+        interactionId,
+        AIAssistantEventType.CUSTOM_EVENT,
+        eventName,
+        undefined,
+        trimmedContext,
+        languageCode,
+        trackingId
+      );
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_GET_SUGGESTED_RESPONSE_SUCCESS,
+        {
+          agentId,
+          orgId,
+          interactionId,
+          eventName,
+          trackingId,
+          context,
+        },
+        ['operational']
+      );
+      LoggerProxy.log('Suggested response request succeeded', loggerContext);
+
+      return response;
+    } catch (error) {
+      LoggerProxy.error('Suggested response request failed', {...loggerContext, error});
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_GET_SUGGESTED_RESPONSE_FAILED,
+        {
+          agentId,
+          interactionId,
+          trackingId,
+          eventName,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+
+      const {error: detailedError} = getErrorDetails(
+        error,
+        METHODS.GET_SUGGESTED_RESPONSE,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+  }
+
   /**
    * Fetches historic transcripts for an interaction.
    * This API is allowed only when real-time transcription feature is enabled.

package/src/services/config/constants.ts

@@ -166,7 +166,7 @@ export const endPointMap = {
   ) =>
     `organization/${orgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}${
       filter && filter.length > 0 ? `&filter=id=in=(${filter})` : ''
-    }&attributes=${attributes}`,
+    }&attributes=${attributes}&desktopProfileFilter=true`,
 
   /**
    * Gets the endpoint for organization info.

package/src/services/config/types.ts

@@ -121,6 +121,14 @@ export const CC_TASK_EVENTS = {
   AGENT_INVITE_FAILED: 'AgentInviteFailed',
   /** Event emitted when a real-time transcript chunk is received */
   REAL_TIME_TRANSCRIPTION: 'REAL_TIME_TRANSCRIPTION',
+  /** Event emitted when an AI assistant suggested response is available */
+  SUGGESTED_RESPONSE: 'SUGGESTED_RESPONSE',
+  /** Event emitted when backend acknowledges it is listening for more context */
+  SUGGESTED_RESPONSE_ACKNOWLEDGE: 'SUGGESTED_RESPONSE_ACKNOWLEDGE',
+  /** Event emitted when a mid-call summary is available */
+  MID_CALL_SUMMARY: 'MID_CALL_SUMMARY',
+  /** Event emitted when a post-call summary is available */
+  POST_CALL_SUMMARY: 'POST_CALL_SUMMARY',
 } as const;
 
 /**

package/src/services/task/TaskManager.ts

@@ -93,7 +93,12 @@ export default class TaskManager extends EventEmitter {
         return;
       }
 
-      task.emit(payload.type, payload.data);
+      switch (payload.type) {
+        case CC_EVENTS.REAL_TIME_TRANSCRIPTION:
+        case CC_EVENTS.SUGGESTED_RESPONSE:
+          task.emit(payload.type, payload.data);
+          break;
+      }
     } catch (error) {
       LoggerProxy.error('Failed to parse RTD WebSocket message', {
         module: TASK_MANAGER_FILE,
@@ -755,7 +760,7 @@ export default class TaskManager extends EventEmitter {
   private requestRealTimeTranscripts(eventType: string, interactionId: string): void {
     const action = TRANSCRIPT_EVENT_MAP[eventType];
     if (!action || !this.apiAIAssistant) return;
-    if (this.configFlags?.aiFeature?.realtimeTranscripts?.enable === false) return;
+    if (this.configFlags?.aiFeature?.realtimeTranscripts?.enable !== true) return;
 
     this.apiAIAssistant
       .sendEvent(

package/src/services/task/ai-docs/AGENTS.md

@@ -217,6 +217,13 @@ cc.on('task:incoming', async (task) => {
 
 > Full list is defined in `TASK_EVENTS` (`types.ts`).
 
+### AI Assistant events on `task`
+
+| Event | When Emitted |
+| --- | --- |
+| `REAL_TIME_TRANSCRIPTION` | A realtime transcript payload is received for the task interaction |
+| `SUGGESTED_RESPONSE` | A final AI Assistant suggestion payload is received for the task interaction |
+
 ---
 
 ## API Reference

package/src/services/task/ai-docs/ARCHITECTURE.md

@@ -400,6 +400,18 @@ this.webSocketManager.on('message', (event) => {
 });
 ```
 
+### RTD / AI Assistant event routing
+
+`TaskManager.handleRealtimeWebsocketEvent()` handles payloads arriving on the realtime subscription socket used for AI features. It:
+
+1. Normalizes the websocket envelope (`payload.data` vs direct payload form)
+2. Resolves the owning task via `conversationId`
+3. Emits `REAL_TIME_TRANSCRIPTION` on the task for transcript payloads
+4. Emits `SUGGESTED_RESPONSE` on the task only when the backend payload is a final suggestion (`data.type === 'SUGGESTION'`)
+5. Ignores `SUGGESTED_RESPONSE_ACKNOWLEDGE` for public SDK emission
+
+This keeps transcript and suggestion delivery aligned on the same per-task event surface.
+
 ---
 
 ## WebRTC Integration

package/src/types.ts

@@ -846,6 +846,27 @@ export type UpdateDeviceTypeResponse = Agent.DeviceTypeUpdateSuccess | Error;
  */
 export type TranscriptAction = 'START' | 'STOP';
 
+/**
+ * Parameters used to request an AI Assistant suggested response.
+ * @public
+ * @example
+ * const params: SuggestedResponseParams = {
+ *   interactionId: 'interaction-123',
+ *   actionTimeStamp: Date.now(),
+ *   context: 'Need help with credit card payment due date',
+ * };
+ */
+export type SuggestedResponseParams = {
+  /** Agent identifier */
+  agentId: string;
+  /** Interaction identifier for which suggestion should be generated */
+  interactionId: string;
+  /** Optional additional context that should refine the suggestion */
+  context?: string;
+  /** Optional language code for suggestions (for example, 'en'). Defaults to 'en'. */
+  languageCode?: string;
+};
+
 /**
  * Supported AI Assistant event categories.
  * @public
@@ -879,6 +900,10 @@ export type AIAssistantEventType = Enum<typeof AIAssistantEventType>;
 export const AIAssistantEventName = {
   /** Request transcript streaming for an interaction */
   GET_TRANSCRIPTS: 'GET_TRANSCRIPTS',
+  /** Request a suggested response for an interaction */
+  GET_SUGGESTIONS: 'GET_SUGGESTIONS',
+  /** Add extra context to refine a suggested response */
+  ADD_SUGGESTIONS_EXTRA_CONTEXT: 'ADD_SUGGESTIONS_EXTRA_CONTEXT',
   /** Request mid-call summary generation */
   GET_MID_CALL_SUMMARY: 'GET_MID_CALL_SUMMARY',
   /** Request post-call summary generation */

package/test/unit/spec/cc.ts

@@ -110,8 +110,10 @@ describe('webex.cc', () => {
 
     mockApiAIAssistant = {
       sendEvent: jest.fn(),
+      getSuggestedResponse: jest.fn(),
       fetchHistoricTranscripts: jest.fn(),
       setAIFeatureFlags: jest.fn(),
+      setAgentId: jest.fn(),
     };
 
     // Mock Services instance

package/test/unit/spec/services/ApiAiAssistant.ts

@@ -57,23 +57,18 @@ describe('ApiAIAssistant', () => {
       'START'
     );
 
-    expect(mockWebex.request).toHaveBeenCalledWith({
-      uri: 'https://api-ai-assistant.produs1.ciscoccservice.com/event',
-      method: HTTP_METHODS.POST,
-      addAuthHeader: true,
-      body: {
-        agentId: 'test-agent-id',
-        orgId: 'test-org-id',
-        eventType: 'CUSTOM_EVENT',
-        eventName: 'GET_TRANSCRIPTS',
-        eventDetails: {
-          data: expect.objectContaining({
-            interactionId: 'interaction-1',
-            action: 'START',
-          }),
-        },
-      },
-    });
+    expect(mockWebex.request).toHaveBeenCalledTimes(1);
+    const requestArgs = (mockWebex.request as jest.Mock).mock.calls[0][0];
+
+    expect(requestArgs.uri).toBe('https://api-ai-assistant.produs1.ciscoccservice.com/event');
+    expect(requestArgs.method).toBe(HTTP_METHODS.POST);
+    expect(requestArgs.addAuthHeader).toBe(true);
+    expect(requestArgs.body.agentId).toBe('test-agent-id');
+    expect(requestArgs.body.orgId).toBe('test-org-id');
+    expect(requestArgs.body.eventType).toBe('CUSTOM_EVENT');
+    expect(requestArgs.body.eventName).toBe('GET_TRANSCRIPTS');
+    expect(requestArgs.body.eventDetails.data.interactionId).toBe('interaction-1');
+    expect(requestArgs.body.eventDetails.data.action).toBe('START');
     expect(result).toEqual({ok: true});
   });
 
@@ -97,6 +92,83 @@ describe('ApiAIAssistant', () => {
     expect(result).toEqual(responseBody as any);
   });
 
+  it('should request suggested response without extra context using sendEvent', async () => {
+    const sendEventSpy = jest.spyOn(apiAIAssistant, 'sendEvent').mockResolvedValue({ok: true});
+    apiAIAssistant.setAIFeatureFlags({suggestedResponses: {enable: true}} as any);
+
+    const result = await apiAIAssistant.getSuggestedResponse({
+      agentId: 'test-agent-id',
+      interactionId: 'interaction-1',
+    });
+
+    expect(sendEventSpy).toHaveBeenCalledTimes(1);
+    const [agentId, interactionId, eventType, eventName, action, context, languageCode, trackingId] =
+      sendEventSpy.mock.calls[0];
+
+    expect(agentId).toBe('test-agent-id');
+    expect(interactionId).toBe('interaction-1');
+    expect(eventType).toBe('CUSTOM_EVENT');
+    expect(eventName).toBe('GET_SUGGESTIONS');
+    expect(action).toBeUndefined();
+    expect(context).toBeUndefined();
+    expect(languageCode).toBe('en');
+    expect(typeof trackingId).toBe('string');
+    expect(trackingId.startsWith('WX_CC_SDK_')).toBe(true);
+    expect(result).toEqual({ok: true});
+  });
+
+  it('should request suggested response with extra context using sendEvent', async () => {
+    const sendEventSpy = jest.spyOn(apiAIAssistant, 'sendEvent').mockResolvedValue({ok: true});
+    apiAIAssistant.setAIFeatureFlags({suggestedResponses: {enable: true}} as any);
+
+    const result = await apiAIAssistant.getSuggestedResponse({
+      agentId: 'test-agent-id',
+      interactionId: 'interaction-1',
+      context: 'Need assistance with credit card payment due date',
+    });
+
+    expect(sendEventSpy).toHaveBeenCalledTimes(1);
+    const [agentId, interactionId, eventType, eventName, action, context, languageCode, trackingId] =
+      sendEventSpy.mock.calls[0];
+
+    expect(agentId).toBe('test-agent-id');
+    expect(interactionId).toBe('interaction-1');
+    expect(eventType).toBe('CUSTOM_EVENT');
+    expect(eventName).toBe('ADD_SUGGESTIONS_EXTRA_CONTEXT');
+    expect(action).toBeUndefined();
+    expect(context).toBe('Need assistance with credit card payment due date');
+    expect(languageCode).toBe('en');
+    expect(typeof trackingId).toBe('string');
+    expect(trackingId.startsWith('WX_CC_SDK_')).toBe(true);
+    expect(result).toEqual({ok: true});
+  });
+
+  it('should treat whitespace-only context as GET_SUGGESTIONS', async () => {
+    const sendEventSpy = jest.spyOn(apiAIAssistant, 'sendEvent').mockResolvedValue({ok: true});
+    apiAIAssistant.setAIFeatureFlags({suggestedResponses: {enable: true}} as any);
+
+    const result = await apiAIAssistant.getSuggestedResponse({
+      agentId: 'test-agent-id',
+      interactionId: 'interaction-1',
+      context: '   ',
+    });
+
+    expect(sendEventSpy).toHaveBeenCalledTimes(1);
+    const [agentId, interactionId, eventType, eventName, action, context, languageCode, trackingId] =
+      sendEventSpy.mock.calls[0];
+
+    expect(agentId).toBe('test-agent-id');
+    expect(interactionId).toBe('interaction-1');
+    expect(eventType).toBe('CUSTOM_EVENT');
+    expect(eventName).toBe('GET_SUGGESTIONS');
+    expect(action).toBeUndefined();
+    expect(context).toBe('');
+    expect(languageCode).toBe('en');
+    expect(typeof trackingId).toBe('string');
+    expect(trackingId.startsWith('WX_CC_SDK_')).toBe(true);
+    expect(result).toEqual({ok: true});
+  });
+
   it('should fail when base URL mapping is not available', async () => {
     (mockWebex.internal.services.get as jest.Mock).mockReturnValue('https://unknown-host.invalid');
 
@@ -129,4 +201,20 @@ describe('ApiAIAssistant', () => {
 
     expect(errorMessage).toBe('Error while performing fetchHistoricTranscripts');
   });
+
+  it('should fail when suggested responses feature is disabled', async () => {
+    apiAIAssistant.setAIFeatureFlags({suggestedResponses: {enable: false}} as any);
+    let errorMessage = '';
+
+    try {
+      await apiAIAssistant.getSuggestedResponse({
+        agentId: 'test-agent-id',
+        interactionId: 'interaction-1',
+      });
+    } catch (error) {
+      errorMessage = (error as Error)?.message || '';
+    }
+
+    expect(errorMessage).toBe('Error while performing getSuggestedResponse');
+  });
 });

package/test/unit/spec/services/config/index.ts

@@ -260,7 +260,7 @@ describe('AgentConfigService', () => {
 
       expect(mockWebexRequest.request).toHaveBeenCalledWith({
         service: mockWccAPIURL,
-        resource: `organization/${mockOrgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}&filter=id=in=(${filter})&attributes=${attributes}`,
+        resource: `organization/${mockOrgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}&filter=id=in=(${filter})&attributes=${attributes}&desktopProfileFilter=true`,
         method: 'GET',
       });
       expect(result).toEqual(mockResponse.body);

package/test/unit/spec/services/task/TaskManager.ts

@@ -253,6 +253,19 @@ describe('TaskManager', () => {
   });
 
   it('should invoke sendEvent for configured start/stop backend events', () => {
+    taskManager.setConfigFlags({
+      isEndTaskEnabled: true,
+      isEndConsultEnabled: true,
+      webRtcEnabled: true,
+      autoWrapup: false,
+      aiFeature: {
+        id: 'ai-feature-1',
+        realtimeTranscripts: {
+          enable: true,
+        },
+      },
+    });
+
     const interactionId = taskId;
     const message = (type: CC_EVENTS) =>
       JSON.stringify({
@@ -316,6 +329,35 @@ describe('TaskManager', () => {
     expect(mockApiAIAssistant.sendEvent).not.toHaveBeenCalled();
   });
 
+  it('should not invoke sendEvent when realtime transcripts config is missing', () => {
+    taskManager.setConfigFlags({
+      isEndTaskEnabled: true,
+      isEndConsultEnabled: true,
+      webRtcEnabled: true,
+      autoWrapup: false,
+      aiFeature: {
+        id: 'ai-feature-1',
+        suggestedResponses: {
+          enable: true,
+        },
+      },
+    });
+
+    const message = (type: CC_EVENTS) =>
+      JSON.stringify({
+        data: {
+          ...taskDataMock,
+          interactionId: taskId,
+          type,
+        },
+      });
+
+    webSocketManagerMock.emit('message', message(CC_EVENTS.AGENT_CONTACT_ASSIGNED));
+    webSocketManagerMock.emit('message', message(CC_EVENTS.AGENT_CONSULTING));
+
+    expect(mockApiAIAssistant.sendEvent).not.toHaveBeenCalled();
+  });
+
   it('should emit REAL_TIME_TRANSCRIPTION from RTD websocket payload', () => {
     const task = taskManager.getTask(taskId);
     const taskEmitSpy = jest.spyOn(task, 'emit');