Skip to content

AGENTS.md

Latest commit

 

History

History
211 lines (147 loc) · 6.36 KB

AGENTS.md

File metadata and controls

211 lines (147 loc) · 6.36 KB

Contact Center Store (@webex/cc-store)

Overview

@webex/cc-store is the shared, singleton MobX store for all Contact Center widgets. It holds global agent, session and task state, proxies SDK events, and exposes convenience APIs for fetching lists (queues, entry points, address book), task lifecycle handling, and common mutations.

Package: @webex/cc-store
Version: See package.json

Why and What is This Used For?

Purpose

The store enables Contact Center widgets to:

  • Initialize and register with the Webex Contact Center SDK
  • Observe global state (teams, device type, login options, agent state, tasks and many more)
  • Handle SDK events (login, logout, multi-login, task lifecycle, agent state changes)
  • Fetch domain data (buddy agents, queues, entry points, address book)
  • Centralize callbacks and error handling for consistent behavior across widgets

Key Capabilities

  • Singleton state via MobX observables
  • Event wiring to SDK (TASK_EVENTS and CC_EVENTS from the SDK)
  • Task list management and current task tracking
  • Data-fetching helpers - Async methods that fetch domain data from SDK APIs (buddy agents, queues, entry points, address book, access token)
  • State management methods - Setters and mutators for store observables (device type, dial number, team ID, current task, etc.)
  • Error propagation via setOnError
  • Feature flags parsing from Agent's profile received from SDK

Examples and Usage

Basic Initialization

import store from '@webex/cc-store';

// Option A: If you already have a Webex instance, best for existing webex enabled apps
await store.init({
  webex: webexInstance,
});

// Option B: Let the store initialize Webex for you, best for new apps
await store.init({
  webexConfig: {
    /* sdk config */
  },
  access_token: authToken /* to be provided by the user */,
});

Registration (when Webex is ready)

// If you need explicit (re-)registration using an existing webex
await store.registerCC(someWebexInstance);

Observing State in React

import {observer} from 'mobx-react-lite';
import store from '@webex/cc-store';

const Header = observer(() => {
  return (
    <div>
      <div>Agent ID: {store.agentId}</div>
      <div>Logged In: {store.isAgentLoggedIn ? 'Yes' : 'No'}</div>
      <div>Device: {store.deviceType}</div>
      <div>Team: {store.teamId}</div>
    </div>
  );
});

Setting Up Error Callback

import store from '@webex/cc-store';

store.setOnError((componentName, error) => {
  console.error(`Error from ${componentName}`, error);
  // forward to telemetry
});

Subscribing/Unsubscribing to SDK Events on contact center object

import store, {CC_EVENTS, TASK_EVENTS} from '@webex/cc-store';

const onLogin = (payload) => console.log('Login success:', payload);
store.setCCCallback(CC_EVENTS.AGENT_STATION_LOGIN_SUCCESS, onLogin);

// Later
store.removeCCCallback(CC_EVENTS.AGENT_STATION_LOGIN_SUCCESS, onLogin);

Subscribing/Unsubscribing to Task Events on task object

import store, {TASK_EVENTS} from '@webex/cc-store';

// Choose a task (e.g., current task)
const taskId = store.currentTask?.data?.interactionId;
if (taskId) {
  const handleMedia = (track) => {
    // e.g., use track for call control audio
    console.log('Media track received', track?.kind);
  };

  // Subscribe to a task event
  store.setTaskCallback(TASK_EVENTS.TASK_MEDIA, handleMedia, taskId);

  // Later, unsubscribe
  store.removeTaskCallback(TASK_EVENTS.TASK_MEDIA, handleMedia, taskId);
}

Fetching Lists

These helper methods centralize SDK data-fetching in the store so widgets can access domain data (agents, queues, contacts) without directly importing the SDK. This ensures consistent error handling, avoids circular dependencies, and enables data transformation (like filtering queues by media type). Widgets like Transfer/Consult use getBuddyAgents() and getQueues() for populating dropdowns, while Outdial widgets use getEntryPoints() and getAddressBookEntries() for contact selection.

// Buddy agents for current task media type
const buddies = await store.getBuddyAgents();

// Queues for a channel
const {data: queues} = await store.getQueues('TELEPHONY', {page: 0, pageSize: 25});

// Entry points
const entryPoints = await store.getEntryPoints({page: 0, pageSize: 50});

// Address book (no-op if disabled)
const addressBook = await store.getAddressBookEntries({page: 0, pageSize: 50});

Mutating Common State

store.setDeviceType('BROWSER');
store.setDialNumber('12345');
store.setTeamId('teamId123');
store.setState({id: 'Available', name: 'Available', isSystem: true, isDefault: true});

Key properties and methods

Properties (observable via MobX):

  • teams, loginOptions, idleCodes, wrapupCodes, featureFlags
  • agentId, agentProfile, isAgentLoggedIn, deviceType, dialNumber, teamId
  • currentTask, taskList, currentState, lastStateChangeTimestamp, lastIdleCodeChangeTimestamp
  • showMultipleLoginAlert, currentTheme, customState, isMuted, isAddressBookEnabled

Methods:

  • init(params), registerCC(webex?)
  • setOnError(cb), setCCCallback(event, cb), removeCCCallback(event)
  • refreshTaskList(), setCurrentTask(task, isClicked?)
  • setDeviceType(option), setDialNumber(value), setTeamId(id)
  • setCurrentState(stateId), setState(state | {reset:true})
  • getBuddyAgents(mediaType?), getQueues(mediaType?, params?)
  • getEntryPoints(params?), getAddressBookEntries(params?)

For full types, see src/store.types.ts.

Dependencies

See exact versions in package.json

Runtime

Package Purpose
@webex/contact-center SDK integration (methods/events)
mobx Observable state management

Dev/Test

TypeScript, Jest, ESLint, Webpack (see package.json).

Installation

yarn add @webex/cc-store

Additional Resources

For detailed store architecture, event flows, and sequence diagrams, see architecture.md.

To obtain Webex access tokens for development and testing, visit the Webex Developer Portal.

Last Updated: 2025-11-26