@webex/contact-center 3.12.0-next.73 → 3.12.0-next.74

package/src/metrics/behavioral-events.ts

@@ -352,6 +352,34 @@ const eventTaxonomyMap: Record<string, BehavioralEventTaxonomy> = {
     verb: 'fail',
   },
 
+  // Conference Exit
+  [METRIC_EVENT_NAMES.TASK_CONFERENCE_EXIT_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_conference_exit',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.TASK_CONFERENCE_EXIT_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_conference_exit',
+    verb: 'fail',
+  },
+
+  // Switch Call
+  [METRIC_EVENT_NAMES.TASK_SWITCH_CALL_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'task_switch_call',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.TASK_SWITCH_CALL_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'task_switch_call',
+    verb: 'fail',
+  },
+
   // upload logs
   [METRIC_EVENT_NAMES.UPLOAD_LOGS_SUCCESS]: {
     product,

package/src/metrics/constants.ts

@@ -129,6 +129,10 @@ export const METRIC_EVENT_NAMES = {
   TASK_CONFERENCE_END_FAILED: 'Task Conference End Failed',
   TASK_CONFERENCE_TRANSFER_SUCCESS: 'Task Conference Transfer Success',
   TASK_CONFERENCE_TRANSFER_FAILED: 'Task Conference Transfer Failed',
+  TASK_CONFERENCE_EXIT_SUCCESS: 'Task Conference Exit Success',
+  TASK_CONFERENCE_EXIT_FAILED: 'Task Conference Exit Failed',
+  TASK_SWITCH_CALL_SUCCESS: 'Task Switch Call Success',
+  TASK_SWITCH_CALL_FAILED: 'Task Switch Call Failed',
 
   TASK_OUTDIAL_SUCCESS: 'Task Outdial Success',
   TASK_OUTDIAL_FAILED: 'Task Outdial Failed',
@@ -138,11 +142,10 @@ export const METRIC_EVENT_NAMES = {
   WEBSOCKET_DEREGISTER_SUCCESS: 'Websocket Deregister Success',
   WEBSOCKET_DEREGISTER_FAIL: 'Websocket Deregister Failed',
 
-  // WebSocket message events
-  WEBSOCKET_EVENT_RECEIVED: 'Websocket Event Received',
-
   AGENT_DEVICE_TYPE_UPDATE_SUCCESS: 'Agent Device Type Update Success',
   AGENT_DEVICE_TYPE_UPDATE_FAILED: 'Agent Device Type Update Failed',
+  // WebSocket message events
+  WEBSOCKET_EVENT_RECEIVED: 'Websocket Event Received',
 
   // EntryPoint API Events
   ENTRYPOINT_FETCH_SUCCESS: 'Entrypoint Fetch Success',
@@ -168,9 +171,11 @@ export const METRIC_EVENT_NAMES = {
   CAMPAIGN_PREVIEW_REMOVE_SUCCESS: 'Campaign Preview Remove Success',
   CAMPAIGN_PREVIEW_REMOVE_FAILED: 'Campaign Preview Remove Failed',
 
-  // AI Assistant transcript events
+  // AI Assistant Transcript 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 {
@@ -27,7 +29,7 @@ import {AIFeatureFlags} from './config/types';
 export class ApiAIAssistant {
   private webex: WebexSDK;
   private metricsManager: MetricsManager;
-  public aiFeature: AIFeatureFlags;
+  private aiFeature: AIFeatureFlags;
 
   constructor(webex: WebexSDK) {
     this.webex = webex;
@@ -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.
@@ -201,6 +301,7 @@ export class ApiAIAssistant {
         },
         ['operational']
       );
+
       if (error instanceof Error) {
         throw error;
       }

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

@@ -0,0 +1,238 @@
+# Agent Service - AI Agent Guide
+
+> **Purpose**: Manage agent lifecycle including login, logout, state changes, and buddy agent queries.
+
+---
+
+## Quick Start
+
+```typescript
+const cc = webex.cc;
+
+// Register and login
+const profile = await cc.register();
+await cc.stationLogin({
+  teamId: profile.teams[0].teamId,
+  loginOption: 'BROWSER',
+});
+
+// Set state to Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Get available agents for transfer
+const buddies = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+```
+
+---
+
+## Key Capabilities
+
+- **Station Login**: Login with browser (WebRTC), extension, or dial number
+- **Station Logout**: Logout from current station with reason
+- **State Management**: Toggle between Available/Idle states with aux codes
+- **Buddy Agents**: Query available agents for consult/transfer
+- **Silent Relogin**: Automatic re-authentication on reconnection
+
+---
+
+## API Reference
+
+### Login Options
+
+| Option | Description | Requires dialNumber |
+|--------|-------------|---------------------|
+| `BROWSER` | WebRTC softphone in browser | No |
+| `EXTENSION` | Desk phone extension | Yes |
+| `AGENT_DN` | Direct dial number | Yes |
+
+### Methods
+
+#### `cc.stationLogin(params)`
+
+Login agent to a station.
+
+**Parameters**:
+- `teamId` (string): Team to login to
+- `loginOption` ('BROWSER' | 'EXTENSION' | 'AGENT_DN'): Device type
+- `dialNumber` (string, optional): Required for EXTENSION/AGENT_DN
+
+**Returns**: `Promise<StationLoginResponse>`
+
+**Example**:
+```typescript
+// Browser login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'BROWSER',
+});
+
+// Extension login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'EXTENSION',
+  dialNumber: '1234',
+});
+```
+
+---
+
+#### `cc.stationLogout(params)`
+
+Logout agent from station.
+
+**Parameters**:
+- `logoutReason` (string, optional): 'User requested logout' | 'Inactivity Logout' | 'User requested agent profile update'
+
+**Returns**: `Promise<StationLogoutResponse>`
+
+**Example**:
+```typescript
+await cc.stationLogout({
+  logoutReason: 'User requested logout',
+});
+```
+
+---
+
+#### `cc.setAgentState(params)`
+
+Change agent state (Available/Idle).
+
+**Parameters**:
+- `state` ('Available' | 'Idle'): New state
+- `auxCodeId` (string): Auxiliary code ID
+- `lastStateChangeReason` (string, optional): Reason for change
+- `agentId` (string, optional): Agent ID (defaults to current agent)
+
+**Returns**: `Promise<SetStateResponse>`
+
+**Example**:
+```typescript
+// Go Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Go to Idle with specific code
+await cc.setAgentState({
+  state: 'Idle',
+  auxCodeId: 'break-code-123',
+  lastStateChangeReason: 'Coffee break',
+});
+```
+
+---
+
+#### `cc.getBuddyAgents(params)`
+
+Get list of agents for consult/transfer.
+
+**Parameters**:
+- `state` (string, optional): Filter by state ('Available', 'Idle')
+- `mediaType` (string): Media type filter ('telephony', 'chat', 'social', 'email')  
+**Returns**: `Promise<BuddyAgentsResponse>`
+
+**Example**:
+```typescript
+const response = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+
+response.data.agentList.forEach(agent => {
+  console.log(`${agent.agentName} (${agent.state})`);
+});
+```
+
+---
+
+## Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `agent:stationLoginSuccess` | `StationLoginSuccessResponse` | Login succeeded |
+| `agent:stationLoginFailed` | Error | Login failed |
+| `agent:logoutSuccess` | `LogoutSuccess` | Logout succeeded |
+| `agent:logoutFailed` | Error | Logout failed |
+| `agent:stateChange` | `StateChangeSuccess` | State changed (any source) |
+| `agent:stateChangeSuccess` | `StateChangeSuccess` | State change succeeded |
+| `agent:stateChangeFailed` | Error | State change failed |
+| `agent:multiLogin` | Object | Multi-login detected |
+| `agent:reloginSuccess` | `ReloginSuccess` | Silent relogin succeeded |
+| `agent:dnRegistered` | Object | DN registration complete |
+
+### Event Usage
+
+```typescript
+cc.on('agent:stateChange', (event) => {
+  console.log(`State: ${event.subStatus}, AuxCode: ${event.auxCodeId}`);
+});
+
+cc.on('agent:multiLogin', (event) => {
+  console.warn('Another session detected');
+});
+```
+
+---
+
+## Agent States
+
+The `AgentState` type (`'Available' | 'Idle' | 'RONA' | string`) is extensible -- the `string` union member allows backend-defined states beyond the known values listed below.
+
+| State | SubStatus | Description |
+|-------|-----------|-------------|
+| LoggedIn | Available | Ready to receive tasks |
+| LoggedIn | Idle | On break or not ready (uses aux code for sub-reason) |
+| RONA | - | Rang but no answer; agent failed to accept offered task |
+| LoggedOut | - | Not logged in |
+| LoggedIn | *(custom)* | Additional org-specific states defined via aux codes |
+
+> **Note**: `AgentState` is a union with `string`, so consumers should handle unknown state values gracefully rather than exhaustively matching only the known literals.
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  await cc.stationLogin(params);
+} catch (error) {
+  console.error('Login failed:', error.message);
+  // Access error details
+  if (error.data) {
+    console.error('Field:', error.data.fieldName);
+    console.error('Message:', error.data.message);
+  }
+}
+```
+
+### Common Error Reasons
+
+| Reason | Description |
+|--------|-------------|
+| `DUPLICATE_LOCATION` | Extension/DN already in use |
+| `INVALID_DIAL_NUMBER` | Invalid phone number format |
+| `AGENT_NOT_FOUND` | Agent doesn't exist (silent relogin) |
+
+---
+
+## Dependencies
+
+- Requires `cc.register()` to be called first
+- Agent profile must be fetched before login
+- WebRTC (BROWSER option) requires mercury connection
+
+---
+
+## Related
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive
+- [`cc.ts`](../../../cc.ts) - Main plugin implementation
+- [`types.ts`](../types.ts) - Type definitions