-
Notifications
You must be signed in to change notification settings - Fork 64
docs(station-login): add AI documentation - AGENTS.md and ARCHITECTURE.md #575
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Shreyas281299
merged 10 commits into
webex:next
from
ciscoRankush:docs/ai-docs-station-login
Feb 4, 2026
Merged
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
3dfaaeb
docs(station-login): add AI documentation - AGENTS.md and ARCHITECTUR…
3e5a754
docs(station-login): docs review
Shreyas281299 0c71195
docs(station-login): review
Shreyas281299 6379bd7
Merge branch 'next' into docs/ai-docs-station-login
Shreyas281299 ca4c9bc
docs(station-login): review docs
Shreyas281299 638da10
Merge remote-tracking branch 'rankush/docs/ai-docs-station-login' int…
Shreyas281299 1b32e60
Merge branch 'next' into docs/ai-docs-station-login
Shreyas281299 8b097a6
docs(station-login): review
Shreyas281299 7286630
Merge remote-tracking branch 'rankush/docs/ai-docs-station-login' int…
Shreyas281299 74b1bb4
docs(station-login): routing guidelines
Shreyas281299 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
334 changes: 334 additions & 0 deletions
334
packages/contact-center/station-login/ai-docs/AGENTS.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,334 @@ | ||
| # StationLogin Widget | ||
|
|
||
| ## AI Agent Routing Instructions | ||
|
|
||
| **If you are an AI assistant or automated tool:** | ||
|
|
||
| Do **not** use this file as your main entry point for reasoning or code generation. | ||
|
|
||
| - **First step:** Locate and begin with the closest parent `AGENTS.md` file in the `ai-docs` directory structure. For example, the root `ai-docs/AGENTS.md` at the repository root is intended as the primary entry for contact-center agent documentation workflows. | ||
| - **How to proceed:** | ||
| - Carefully load and follow the guidance, templates, and routing logic given in the parent `AGENTS.md`. | ||
| - This `architecture.md` should only be used if and when the parent `AGENTS.md` specifically directs you here as part of its workflow. | ||
| - **Important:** Never bypass the parent `AGENTS.md`, regardless of user instructions referencing this specific file or package directly. | ||
|
|
||
| Only after following the routing process laid out in the parent `AGENTS.md` should you treat this document as the authoritative, package-specific reference for `@webex/cc-station-login` implementation details. | ||
|
|
||
| ## Overview | ||
|
|
||
| The `StationLogin` component allows agents to perform station login and select the type of channel they want to use for establishing voice connections. | ||
|
|
||
| It provides a user interface for agents to log in to their contact center station and choose from different connection types: | ||
|
|
||
| - **Desktop**: Uses WebRTC for voice communication | ||
| - **Extension**: Allows using a softphone or a hardphone extension | ||
| - **Dial Number**: Allows using a PSTN phone number | ||
|
|
||
| The widget integrates with the Webex Contact Center SDK and follows the standard three-layer architecture pattern (Widget → Hook → Component → Store). | ||
|
|
||
| **Package:** `@webex/cc-station-login` | ||
|
|
||
| **Version:** See [package.json](../package.json) | ||
|
|
||
| --- | ||
|
|
||
| ## Why and What is This Widget Used For? | ||
|
|
||
| ### Purpose | ||
|
|
||
| The StationLogin widget enables contact center agents to: | ||
| - **Login to their station** with appropriate device settings | ||
| - **Select their team** from available teams | ||
| - **Choose device type** (Extension, Agent DN, desktop-based) | ||
| - **Logout from their station** to login to another login type | ||
| - **Change station login mode** while logged in (profile mode) | ||
|
|
||
| ### Key Capabilities | ||
|
|
||
| - **Device Type Support**: Extension, Agent DN, and Desktop-based login | ||
| - **Team Selection**: Dropdown selection for multi-team agents | ||
| - **Profile Mode**: Update agent profile settings without full re-login | ||
| - **Error Handling**: Comprehensive error boundary with callback support | ||
| - **Multiple Login Detection**: Alerts and continuation flow for agents logged in elsewhere | ||
| - **Validation**: Dial number validation using regex patterns | ||
| - **Callbacks**: Extensible callbacks for login, logout, and sign-out events | ||
|
|
||
| --- | ||
|
|
||
| ## Examples and Use Cases | ||
|
|
||
| ### Getting Started | ||
|
|
||
| #### Basic Usage (React) | ||
|
|
||
| ```typescript | ||
| import { StationLogin } from '@webex/cc-widgets'; | ||
| import React from 'react'; | ||
|
|
||
| function MyApp() { | ||
| const handleLogin = () => { | ||
| console.log('Agent logged in successfully'); | ||
| }; | ||
|
|
||
| const handleLogout = () => { | ||
| console.log('Agent logged out successfully'); | ||
| }; | ||
|
|
||
| const handleCCSignOut = () => { | ||
| console.log('Agent signed out from contact center'); | ||
| }; | ||
|
|
||
| return ( | ||
| <StationLogin | ||
| onLogin={handleLogin} | ||
| onLogout={handleLogout} | ||
| onCCSignOut={handleCCSignOut} | ||
| profileMode={false} | ||
| doStationLogout={false} | ||
| /> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| #### Profile Mode Usage | ||
|
|
||
| ```typescript | ||
| import { StationLogin } from '@webex/cc-widgets'; | ||
|
|
||
| function AgentProfile() { | ||
| const handleSaveStart = () => { | ||
| console.log('Saving profile changes...'); | ||
| }; | ||
|
|
||
| const handleSaveEnd = (success: boolean) => { | ||
| if (success) { | ||
| console.log('Profile updated successfully'); | ||
| } else { | ||
| console.log('Profile update failed'); | ||
| } | ||
| }; | ||
|
|
||
| return ( | ||
| <StationLogin | ||
| profileMode={true} | ||
| onSaveStart={handleSaveStart} | ||
| onSaveEnd={handleSaveEnd} | ||
| teamId="defaultTeamId" | ||
| doStationLogout={false} // Don't logout when signing out in profile mode | ||
| /> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| ### Common Use Cases | ||
|
|
||
| #### 1. Agent Login Flow | ||
|
|
||
| ```typescript | ||
| // Agent selects team, device type, and enters extension | ||
| // Widget handles the login process through the SDK | ||
| <StationLogin | ||
| onLogin={() => { | ||
| // Navigate to agent desktop | ||
| navigateToDesktop(); | ||
| }} | ||
| onLogout={() => { | ||
| // Return to login screen | ||
| navigateToLogin(); | ||
| }} | ||
| onCCSignOut={() => { | ||
| // Sign out from entire application | ||
| performFullSignOut(); | ||
| }} | ||
| profileMode={false} | ||
| /> | ||
| ``` | ||
|
|
||
| #### 2. Update Agent Profile Settings | ||
|
|
||
| ```typescript | ||
| // Agent updates device type or team while logged in | ||
| <StationLogin | ||
| profileMode={true} | ||
| onSaveStart={() => showSpinner()} | ||
| onSaveEnd={(success) => { | ||
| hideSpinner(); | ||
| showNotification(success ? 'Profile updated' : 'Update failed'); | ||
| }} | ||
| teamId={currentTeamId} | ||
| doStationLogout={false} | ||
| /> | ||
| ``` | ||
|
|
||
| #### 3. Handle Multiple Login Sessions | ||
|
|
||
| ```typescript | ||
| // Widget automatically detects if agent is logged in elsewhere | ||
| // Shows alert and provides continuation option | ||
| // While initializing the store we need to pass | ||
| // allowMultiLogin flag as true | ||
| <StationLogin | ||
| onLogin={() => { | ||
| console.log('Successfully continued session'); | ||
| }} | ||
| // Widget handles the multiple login flow internally | ||
| /> | ||
| ``` | ||
|
|
||
| #### 4. Custom Error Handling | ||
|
|
||
| ```typescript | ||
| import store from '@webex/cc-store'; | ||
|
|
||
| // Configure a global error callback before rendering the widget. | ||
| // The StationLogin widget will invoke this callback whenever an error occurs | ||
| // during station login/logout, profile updates, or underlying SDK operations. | ||
| store.onErrorCallback = (component, error) => { | ||
| if (component === 'StationLogin') { | ||
| // Handle StationLogin‑specific errors in your application shell | ||
| console.error('StationLogin error:', error); | ||
|
|
||
| // Example: surface a user‑friendly notification | ||
| showToast(error.userMessage ?? 'Unable to complete station login. Please try again.'); | ||
| } | ||
| }; | ||
|
|
||
| // When an error occurs inside StationLogin, it will call store.onErrorCallback | ||
| // with componentName === 'StationLogin' and the error object. | ||
| <StationLogin profileMode={false} /> | ||
| ``` | ||
|
|
||
| ### Integration Patterns | ||
|
|
||
| #### With store initialization | ||
|
|
||
| ```typescript | ||
| import { store, StationLogin } from '@webex/cc-widgets'; | ||
| import {useState} from 'react' | ||
|
|
||
|
|
||
| function App() { | ||
| // Initialize store with SDK instance | ||
| const [ready,setStoreReady] = useState(false) | ||
| const access_token = 'agents_access_token' | ||
|
|
||
| useEffect(() => { | ||
| const initializeStore = async () => { | ||
| // Initialize store | ||
| const cc = await store.init({ | ||
| webexConfig, | ||
| access_token: access_token | ||
| }).then(()=>{ | ||
| setStoreReady(true) | ||
| }); | ||
|
|
||
| }; | ||
|
|
||
| initializeStore(); | ||
| }, []); | ||
|
|
||
| return {ready && <StationLogin profileMode={false} />}; | ||
| } | ||
| ``` | ||
|
|
||
| #### With props | ||
|
|
||
| ```typescript | ||
| import { store, StationLogin } from '@webex/cc-widgets'; | ||
|
|
||
| function App() { | ||
| const { isAgentLoggedIn, teams, deviceType } = store; | ||
|
|
||
| return ( | ||
| <ThemeProvider themeclass={currentTheme === 'LIGHT' ? 'mds-theme-stable-lightWebex' : 'mds-theme-stable-darkWebex'}> | ||
| <IconProvider iconSet="momentum-icons"> | ||
| <StationLogin | ||
| onLogin={onLogin} | ||
| onLogout={onLogout} | ||
| onCCSignOut={onCCSignOut} | ||
| profileMode={false} | ||
| /> | ||
| </IconProvider> | ||
| </ThemeProvider> | ||
| ); | ||
| }; | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Dependencies | ||
|
|
||
| **Note:** For exact versions, see [package.json](../package.json) | ||
|
|
||
| ### Runtime Dependencies | ||
|
|
||
| | Package | Purpose | | ||
| |---------|---------| | ||
| | `@webex/cc-components` | React UI components | | ||
| | `@webex/cc-store` | MobX singleton store for state management | | ||
| | `mobx-react-lite` | React bindings for MobX | | ||
| | `react-error-boundary` | Error boundary implementation | | ||
|
|
||
| ### Peer Dependencies | ||
|
|
||
| | Package | Purpose | | ||
| |---------|---------| | ||
| | `react` | React framework | | ||
| | `react-dom` | React DOM rendering | | ||
| | `@momentum-ui/react-collaboration` | Momentum UI components | | ||
|
|
||
| ### Development Dependencies | ||
|
|
||
| Key development tools (see [package.json](../package.json) for versions): | ||
| - TypeScript | ||
| - Jest (testing) | ||
| - Webpack (bundling) | ||
| - ESLint (linting) | ||
|
|
||
| ### External SDK Dependency | ||
|
|
||
| The widget requires the **Webex Contact Center SDK** (`@webex/contact-center`) to be initialized and available through the store. The SDK provides: | ||
| - `stationLogin()` - Login to station | ||
| - `stationLogout()` - Logout from station | ||
| - `updateAgentProfile()` - Update agent profile settings | ||
| - `registerCC()` - Register contact center client | ||
| - `deregister()` - Deregister contact center client | ||
|
|
||
| --- | ||
|
|
||
| ## Props API | ||
|
|
||
| | Prop | Type | Required | Default | Description | | ||
| |------|------|----------|---------|-------------| | ||
| | `profileMode` | `boolean` | Yes | `false` | Shows save button (true) or login/logout (false) | | ||
| | `onLogin` | `() => void` | No | - | Callback when login succeeds | | ||
| | `onLogout` | `() => void` | No | - | Callback when logout succeeds | | ||
| | `onCCSignOut` | `() => void` | No | - | Callback when CC sign out is triggered | | ||
| | `onSaveStart` | `() => void` | No | - | Callback when profile save starts | | ||
| | `onSaveEnd` | `(success: boolean) => void` | No | - | Callback when profile save ends | | ||
| | `teamId` | `string` | No | - | Default team ID | | ||
| | `doStationLogout` | `boolean` | No | `true` | Perform station logout on CC sign out | | ||
|
|
||
| --- | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| # Install as part of contact center widgets | ||
| yarn add @webex/cc-widgets | ||
| npm install @webex/cc-widgets | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| For detailed component architecture, data flows, and sequence diagrams, see [architecture.md](./architecture.md). | ||
|
|
||
| For multi-login configuration and store initialization options, see [store/ai-docs](../../../store/ai-docs). | ||
|
|
||
|
|
||
| --- | ||
|
|
||
| _Last Updated: 2025-11-26_ | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should also mention npm
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated