Webex JS SDK

The @webex/contact-center package provides a suite of APIs and types for managing Contact Center operations, including agent routing, task management, and user preferences. The package is structured around several core contracts:

• contact-center.plugin: The main entry point, implementing IContactCenter via the ContactCenter class.
• contact-center.routing-agent: Provides the routingAgent service for agent lifecycle management (login, logout, state changes).
• contact-center.task: Manages Task instances and their associated lifecycles.
• contact-center.user-preference: Handles user-specific configuration via methods like getUserPreference, createUserPreference, updateUserPreference, and deleteUserPreference.
• contact-center.data: Provides access to AddressBook, ApiAIAssistant, and various SDK data response types.

All public APIs follow semantic versioning (semver) for stability.

The @webex/contact-center package is a Webex SDK plugin designed for building Contact Center agent applications using TypeScript or JavaScript. It acts as a plugin for the Webex SDK host and provides a high-level API for managing the lifecycle of an agent session and handling various communication tasks.

Key capabilities include:

• Agent Session Management: Handling registration, login, logout, and state changes.
• Task Handling: Managing inbound/outbound calls, chat, transfers, and conferences.
• Real-time Events: Receiving WebSocket-based notifications for agent and task events.
• Browser-based Calling: Integrating WebRTC for browser-based softphones.
• Metrics & Diagnostics: Built-in telemetry and log uploading.
• Answer on Webex: Support for accepting, declining, muting, and DTMF for voice offers when using Webex App desktop calling (via enableWxBetterTogether).

The @webex/contact-center package is organized into several functional modules. Use the following registry to identify which specification document to consult based on the area of the SDK you are working with:

• src: The main plugin surface, registration lifecycle, public method delegation, and application-facing event routing. (See ai-docs/contact-center-spec.md)
• src/metrics: Telemetry for behavioral, operational, and business data (timing, taxonomy, queuing, and submission). (See src/metrics/ai-docs/metrics-spec.md)
• src/services: Composition and bootstrap order for backend request, realtime, data, and WebRTC services. (See src/services/ai-docs/services-spec.md)
• src/services/agent: Agent lifecycle (login, logout, state-change, buddy-agent, device-update, and silent-relogin).
• src/services/config: Remote configuration retrieval (organization, agent, team, profile, auxiliary-code, dial-plan, and features).
• src/services/core: Authenticated HTTP, WebSocket lifecycle, request correlation, reconnect/keepalive, and error normalization.
• src/services/task: Task creation, media behavior, call-control, lifecycle orchestration, and task events.
• src/services/task/state-machine: Deterministic task lifecycle states, transition guards/actions, and state-derived UI control.
• src/utils: Shared pagination contracts and in-memory page caching.

The CallHistory module provides a comprehensive interface for managing and retrieving user call history. Key capabilities include:

• Fetch Call History: Retrieve records with configurable date ranges, record limits, and sort orders (ASC/DESC).
• Sorting: Supports sorting by startTime or endTime. The default sort is endTime in descending order.
• Update Missed Calls: Mark missed call records as read by providing endTime and sessionId pairs.
• Delete Call History Records: Remove specific records using endTime and sessionId pairs.
• Real-Time Session Events: Listen for lifecycle events via Mercury WebSocket events, including callSessionEventInclusive, callSessionEventLegacy, callSessionEventViewed, and callSessionEventDeleted.
• Backend-Specific Features:
  • WXC: Automatically includes shared session types (WEBEXCALLING_SHARED) via the includeSharedSessions=true parameter.
  • UCM: Enriches records with ucmLineNumber by matching cucmDN against the UCM Lines API.

The Contacts module provides a unified interface for managing user contacts and contact groups. It handles the complexity of different contact types and security requirements automatically.

Key Capabilities

• Fetch Contacts & Groups: Retrieves all contacts and groups. It automatically decrypts CUSTOM contacts and resolves CLOUD contacts via SCIM in batches of 50.
• Create Contact: Creates new CUSTOM or CLOUD contacts with transparent encryption. If no group is specified, it auto-assigns the contact to the default group.
• Delete Contact: Removes a contact by contactId and evicts it from the local in-memory cache.
• Create Contact Group: Creates a new group with an encrypted display name. It automatically manages KMS Resource Objects if no encryption key exists.
• Delete Contact Group: Deletes a group by groupId and removes it from the local cache.
• Transparent Encryption: Automatically encrypts and decrypts sensitive fields such as displayName, firstName, lastName, emails, phoneNumbers, sipAddresses, addressInfo, avatarURL, companyName, and title.
• CLOUD Contact Resolution: Uses SCIM to enrich CLOUD contacts with directory data (e.g., department, manager, avatar) in batches of 50.
• Default Group Management: Automatically ensures an "Other contacts" group exists to prevent ungrouped contacts.

The CallRecording module provides several core capabilities for managing and retrieving Webex call recordings:

• List Recordings: Retrieves the current user's converged recordings. Supports optional time-range filters (from/to), status filters, and pagination.
• Get Recording: Fetches a single recording by its id, including temporary direct download links.
• Get By Call Session: Returns all recordings tied to a specific callSessionId. Note that this is performed via client-side filtering of the list results.
• Get Metadata: Fetches detailed metadata for a recording, such as owner, session, participants, media streams, and extension data.
• Real-Time Recording Events: Re-emits Mercury convergedRecordings.* events as typed callRecording:* events, allowing for real-time synchronization of created, updated, or deleted states.
• Error Handling & Logging: Uses standardized error handling via serviceErrorCodeHandler with automatic log uploads on failure.