Five9 Telephony Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Five9 Telephony Integration provides a clean ES module wrapper for the Five9 CRM SDK within the Care Ops frontend. Its primary purpose is to facilitate communication between the RoundingWell application and the Five9 Agent Desktop Toolkit (ADT), enabling features such as Click-to-Dial, call logging, and interaction tracking.
The integration is architected as a standalone workspace package (@roundingwell/care-ops-five9) that manages the lifecycle of the vendor SDK. It includes mechanisms for automated SDK updates, a patched UMD wrapper to support ES modules, and a silencer for noisy vendor logging.
Sources: packages/care-ops-five9/README.md:1-10, packages/care-ops-five9/AGENTS.md:1-5
Architecture and SDK Management
The integration architecture centers around a managed vendor SDK file and an auto-generated entry point. The system avoids global namespace pollution by capturing vendor globals and then deleting them from the window object.
SDK Lifecycle and Maintenance
The SDK is maintained via an automated script, update-sdk.js, which performs the following tasks:
- Download: Fetches the latest version of the Five9 CRM SDK from the official vendor URL.
- Validation: Scans the downloaded content for mandatory Five9 markers and API structures.
- Patching: Modifies the UMD wrapper to use
globalThisinstead ofthis(fixing compatibility with ES modules) and injects a console silencer to suppress verbose vendor logs. - Analysis: Dynamically detects available APIs (e.g.,
interactionApi,crmApi) and Enums (e.g.,ApiErrorCode). - Generation: Produces the
sdk/index.jsfile with clean named exports.
Sources: packages/care-ops-five9/update-sdk.js:15-85, packages/care-ops-five9/README.md:27-41
Data Flow Diagram
The following diagram illustrates how the SDK is updated and consumed by the application:
The update process ensures that the latest vendor features are available while maintaining local stability through fallback mechanisms.
Sources: packages/care-ops-five9/update-sdk.js:90-130, packages/care-ops-five9/package.json:9-12
API Modules and Interfaces
The integration exposes several functional modules through the @roundingwell/care-ops-five9 package. These modules allow the application to interact with different facets of the Five9 telephony system.
Core API Modules
| Module | Description |
|---|---|
interactionApi | Manages call, chat, and email interaction lifecycles. |
crmApi | Provides hooks for CRM-specific actions like search and screen pop. |
hookApi | Allows intercepting and modifying standard Five9 operations. |
applicationApi | Tracks application lifecycle and login states. |
customMethodsApi | Establishes communication channels between customization bundles and iframes. |
Sources: packages/care-ops-five9/README.md:17-25, packages/care-ops-five9/sdk/five9.crm.sdk.js:1160-1200
Interaction Handling
The interactionApi is the primary interface for handling telephony events. It supports subscriptions to various call states and triggers actions like Click-to-Dial.
Dialer Service Integration
The application consumes the Five9 package via a DialerService located in the main app's service layer. This service acts as a provider-agnostic bridge.
Initialization and Artifacts
The DialerService initializes the Five9 provider by passing a DOM region for the overlay, the organization name, and a patients collection. When a call is completed, the service saves a five9-call-log artifact via the application's radio channels.
// Example of artifact saving in DialerService
service.five9Call({
callData: { interactionId: 'abc1234' },
callLogData: { callDuration: 42, disposition: 'completed' }
});
Sources: src/js/services/dialer.test.js:45-68, src/js/services/dialer.test.js:77-85
Configuration Options
Initialization requires specific bootstrap and settings data:
- Provider Selection: Determined by the
dialersetting (e.g., 'five9'). - Organization Context: Retrieved from the bootstrap channel to identify the provider environment.
- Patient Linking: The service maps active calls to patient models by searching for phone numbers or using active action context.
Sources: src/js/services/dialer.test.js:103-120, src/js/services/dialer.test.js:145-165
Technical Guardrails
- No Manual Edits: The file
sdk/five9.crm.sdk.jsis treated as vendor code and should only be modified viaupdate-sdk.js. - Global Cleanup: The wrapper ensures that
window.Five9andwindow.crmSdkVersionare deleted after initialization to prevent conflicts with other global scripts. - ESM Compatibility: The SDK is strictly wrapped as an ES module to fit the project's Vite-based build system.
Sources: packages/care-ops-five9/AGENTS.md:7-11, packages/care-ops-five9/README.md:43-48, CLAUDE.md:16-19
The Five9 Telephony Integration is a robust, isolated module that provides deep telephony capabilities while shielding the core application from the complexities of vendor SDK management and global namespace pollution. Through the DialerService, it enables seamless patient-contextual calling and automatic call logging.