Widget Lifecycle

The Agent App is a Genesys Cloud Interaction Widget that runs within the agent desktop. It follows a specific lifecycle tied to the Genesys conversation state.

Initialization sequence

sequenceDiagram
    participant GC as Genesys Cloud
    participant Widget as Agent App Widget
    participant API as MaxConf API
    participant Pexip as Conference Node

    GC->>Widget: Load widget (conversationId in URL params)
    Widget->>GC: OAuth Implicit Grant login
    GC-->>Widget: accessToken + conversationId
    Widget->>GC: GET /conversations/{id}
    GC-->>Widget: Conversation details (participants, queue)
    Widget->>Widget: Extract VMR name from customer ANI name
    Widget->>API: GET /public/room/{vmr_name}<br/>(x-auth-token: accessToken)
    API-->>Widget: Room details (name, pin, tag)
    Widget->>Widget: Create PexRTC wrapper
    Widget->>GC: Subscribe to call events<br/>(v2.users.{userId}.conversations.calls)
    Note over Widget: Waiting for agent to answer...
    GC->>Widget: Call event: agent state = "connected"
    Widget->>Pexip: makeCall() + muteAudio()
    Note over Widget,Pexip: Video session active (audio muted)

Call state handling

The widget subscribes to Genesys Cloud notification events and responds to agent state changes:

Agent State	Widget Action
connected (first time)	Initiates WebRTC call, mutes audio
held	Mutes video + audio for both guest and agent; unmutes Genesys host audio
connected (after hold)	Restores video + audio for all participants
muted	Syncs audio mute state to Pexip participants
disconnected	Disconnects guest, then disconnects all

Hold behaviour

When an agent places the call on hold:

1. The citizen’s video feed is paused (video muted on guest participant)
2. The agent’s camera is turned off
3. The Genesys SIP participant audio is unmuted (so hold music plays)

When the agent resumes:

1. Citizen video is restored
2. Agent camera is re-enabled
3. Normal audio routing resumes

ID Check integration

For specific queues (configured by queue ID), the widget also:

1. Opens the citizen’s tag URL in a new browser window (the ID check page)
2. Provides a “Relaunch” button in case the window is closed

This allows the agent to see both the citizen’s video feed and their identity verification page simultaneously.

Configuration

All environment-specific values are in scripts/config.js:

Setting	Purpose
apiUri	MaxConf API base URL for room lookups
genesys.region	Genesys Cloud region (cac1.pure.cloud)
genesys.oauthClientID	OAuth client for implicit grant (varies by hostname)
pexip.conferenceNode	Conference node FQDN for WebRTC connections
pexip.conferencePin	Host PIN for agent entry
pexip.conferencePrefix	Display name prefix (ga = Genesys Agent)

OAuth client selection

The widget uses different OAuth clients based on the deployment hostname:

Hostname pattern	OAuth Client	Genesys Org
*.azurestaticapps.net	fdc5434f-...	maximuscanada-dev (preview)
Production domain	4179e85b-...	maximuscanada (UAT/prod)

Deployment

The Agent App is deployed as an Azure Static Web App. It has no build step - the src/ directory is served directly. Static Web App configuration (staticwebapp.config.json) handles routing and headers.

The widget URL is registered in Genesys Cloud under Admin > Integrations > Interaction Widget with the URL pattern:

https://{static-web-app-domain}/?conversationid={{pcConversationId}}

Genesys substitutes {{pcConversationId}} with the active conversation ID when loading the widget.