Skip to content

ClearConnect PSP demo

Status: Current | Last reviewed: 2026-10-08

ClearConnect hosts the supplied PSP prototype at https://clearconnect.vanguard.dev.trueserve.deloitte.com. The welcome call is a Genesys outbound call between the signed-in coordinator and a real participant playing Ashley. TrueServe listens to both channels and sends events into the existing case workspace.

The source is apps/clearconnect. The presenter guide covers the browser steps. Other chapters retain the supplied prototype workflows; the live integration described here is the welcome call and coordinator Pacey Q&A.

Runtime and routing

sequenceDiagram
    participant Agent as Coordinator browser
    participant App as ClearConnect API
    participant Genesys as Genesys Cloud
    participant Proxy as Existing AudioHook proxy
    participant Connector as Private Genesys connector
    participant TS as TrueServe Copilot
    Agent->>App: Genesys authorization-code sign-in
    Agent->>App: Dial participant number
    App->>Genesys: Create call with queue and CONNECTOR_URL attributes
    Genesys-->>Agent: WebRTC softphone session
    Genesys->>Proxy: Stereo AudioHook
    Proxy->>App: Resolve CONNECTOR_URL and relay audio
    App->>Connector: Validate call capability and conversation, relay audio
    Connector->>TS: AudioHook session for agent 4871
    TS-->>App: Transcripts, choices, coaching and summary
    App-->>Agent: Authenticated SSE through @trueserve/sdk

This reuses TrueServe AudioHook Proxy (a7bd010c-b2a5-402f-80fd-542307a95f46) at wss://genesys-proxy.trueserve.deloitte.com/audiohook. The reference Architect flow is TrueServe Orchestrator Demo Line (28ac7c5f-5679-4317-b9bc-dab58a7f647c), whose Agent Assist task sets CONNECTOR_URL. ClearConnect supplies the same attribute in the initial POST /api/v2/conversations/calls request, before AudioHook starts. The proxy scans all participants for this attribute, including the outbound agent participant. No shared integration URI or organisation-wide mapping is changed.

The URL includes the published Copilot ID, an application call ID and a call-scoped capability. The API admits audio only when the stored Genesys conversation ID matches an active application call. Treat the full URL as sensitive during that call. The app's ingress and Uvicorn omit access logs. The existing proxy is a separate deployment; its logging policy is owned there.

The private connector is a second process using the existing genesys-connector-go binary. Its lookup endpoint always resolves ClearConnect to agent 4871 and the existing Deloitte Genesys integration. The public ingress denies /api/genesys/lookup. The internal hop authenticates separately because the external proxy terminates the original Genesys signature.

Resource Vanguard value
Welcome-call Copilot 4871 — ClearConnect Welcome Call Copilot
Coordinator chat agent 4872 — ClearConnect Pacey Assistant
Genesys queue 4fe147fc-2a88-48b6-9b73-ec821f7ab80f — ClearConnect Welcome Calls
Genesys OAuth client 2d971bec-bd9e-4a2c-b703-f74795b20373 — ClearConnect Vanguard
Genesys region usw2.pure.cloud
Known demo operator Demo User, already a queue member
Application database / role tsf_clearconnect
API 127.0.0.1:8075
Dedicated connector 127.0.0.1:8076
Host static assets /var/www/clearconnect
Host nginx configuration /etc/nginx/conf.d/zz-clearconnect.conf
Process supervisor .local-data/clearconnect/overmind.sock

Other coordinators use their own Genesys sign-in, a selected WebRTC phone, outbound-call permissions and membership of the ClearConnect queue.

The browser keeps autoConnectSessions: true and disableAutoAnswer: true. The app accepts only the expected pending conversation. The SDK then accepts the subsequent SDP offer and attaches microphone/speaker media. Accepting only the pending invitation with automatic media connection disabled leaves the coordinator leg unanswered; Genesys times it out before dialing the participant.

A newly created call can briefly return 404 from Genesys's call read endpoint. The API tolerates that result for the first 15 seconds of dialing and polls the same conversation; it never retries the outbound POST. Successful polling clears only the polling error, preserving separate phone/media errors. A terminal connection error before participant answer is shown as a failed call, with a specific browser-connection message for Genesys's connection-timeout code.

Authentication and persistence

The browser signs into Genesys using the authorization-code grant. The API checks one-time state and the configured organisation, then creates an eight-hour opaque, HTTP-only session. Provider tokens are encrypted in the separate application database. Token refresh is serialized per session. Browser mutations require the ClearConnect origin, and each call/control/event route verifies the signed-in user's ownership.

Genesys access tokens are returned only to the signed-in page for the WebRTC SDK. The TrueServe runtime token, OAuth client secret and internal connector key stay in the API. None belong in Vite environment variables or browser storage.

backend/serve.py is the hosted entrypoint. It mounts PSP routes and the ClearConnect authentication/call boundary. The imported backend/main.py, ElevenLabs routes, generic customer WebSockets, IMAP pollers and Chroma startup are outside this hosted runtime. Mail/SMS delivery is not configured by the ClearConnect launcher; document actions report their actual delivery state.

Four application tables hold OAuth attempts, agent sessions, calls and event receipts. Migration clearconnect001_genesys_calls follows the imported PSP migrations in the isolated database. An index allows one active ClearConnect call per Genesys user. The explicit demo Reset clears finished call/event rows with the patient's other sample data. It refuses to reset a patient with an active Genesys call; dialing and resetting lock the same case row.

Event contract

The browser uses genesys-cloud-webrtc-sdk 14.2.6 and the repository @trueserve/sdk tarball 1.0.0, SHA-256 87a8d2b3f899dfb497ad33789bec2b32ab4019a99e5cc6dd504eedb8d003203d. The TrueServe API resolver points the SDK at the app's authenticated SSE route. It uses the TrueServe conversation UUID resolved from the Genesys external ID; the integer conversationId inside individual events is not that address.

TrueServe event ClearConnect behavior
interim_transcript, final_transcript, refined_transcript Replace/revise stable transcript lines, preserving patient and coordinator attribution
suggestion with data.suggestion_type=form_filling and form_id=welcome-intake Apply explicit yes/no service choices and contact preferences
UI_RENDER / updateComponents Read native flat CoachingCard and SummaryCard components
STATUS with nested or direct status=ended Finish live collection and reconcile the persisted wrap-up
Stored copilot_summary Read its ui_render envelope for the post-call summary

Transcript revisions are local to the interim, final and refined variants. A final revision 1 replaces interim revision 2; compare revision numbers only within the same variant. Late interim replay cannot replace finalized text.

The intake fields are copay_assistance, nurse_educator, peer_support, adherence_reminders, concierge_support, preferred_channel, preferred_language, callback_window and next_step. The adapter accepts field confidence from 0.8 through 1.0, including explicit refusals. It rejects NaN confidence, duplicate receipts and older form/card revisions. Choices update the PSP enrollment tables; preferences update the case. Outreach/audit rows are written in the same transaction as the receipt.

A server collector continues independently of the browser and resumes recent calls after an API restart. Summaries can arrive after the end status, so the collector reads the persisted wrap-up for up to a minute. A suggestion to send a packet or arrange a callback does not mark either action completed.

Pacey Q&A starts a text conversation with agent 4872, waits for its authorization record, supplies the current case evidence and call choices, reads the response, then closes the text session.

Operate and validate

See the application README for commands. Private runtime configuration and validation evidence live in .local-data/clearconnect with mode 0700/0600. The startup hook is appended to the existing .local-data/wake-up-local.sh; it preserves other personal services.

The provisioner publishes agents through the native Agent Studio publish route, including the CCaaS allow-list. It reuses saved identifiers on reruns and revokes its temporary publication token. The runtime agents:run token has a 90-day expiry; rotate it in the private configuration and restart only the ClearConnect API before expiry.

Validation has separate scopes:

  • Unit checks cover call ownership, duplicate dial prevention, session expiry, cross-origin requests, event replay, refusals and native event envelopes.
  • Browser checks exercise HTTPS, the OAuth redirect, case loading, the empty number guard, the signed-in coordinator and Agent Studio Q&A.
  • The browser check's --copilot mode loads a separate fixture linked to the successful synthetic conversation. The real SDK and authenticated SSE replay render both speakers, service acceptances/refusals and the stored summary.
  • validate_audiohook.py sends synthetic stereo speech through the deployed AudioHook endpoint, the real connector, STT, Copilot and authenticated app SSE. It removes its separate fixture case/session afterward.
  • An answered PSTN call requires a coordinator to sign in and the participant to answer the number entered in the app. Synthetic audio validation does not establish that final phone/media check.

See also