This Playbook shows how to build an integration that automatically mirrors a Webex user's real-time presence state into their Cisco Finesse (UCCX/UCCE) agent status, eliminating the manual step of toggling Finesse between READY and NOT_READY when agents join Webex calls or meetings.
The integration is a Node.js server that uses a Webex Bot token to subscribe to presence events via the Webex Mercury WebSocket. When a monitored agent's Webex presence changes, the server maps the Webex presence state to a Finesse agent state and applies it automatically. Five Webex presence states trigger a Finesse NOT_READY transition:
- Do Not Disturb (reason code: "Webex DND")
- Active Webex Call (reason code: "Webex Call")
- Active Webex Meeting (reason code: "Webex Meeting")
- Presenting in a Webex Meeting (reason code: "Webex Meeting")
- Unknown/Unavailable (reason code: "Webex Unavailable")
When the Webex presence clears, the agent is automatically returned to READY.
Two operating modes are provided:
Gadget mode (recommended): The server pushes presence updates to a Finesse XML gadget running in the agent's desktop browser via Socket.io. The gadget calls the Finesse client-side JavaScript API (user.setState) to set the agent's own status, including the specific NOT_READY reason code. This mode requires adding a gadget entry to the Finesse desktop layout and is the only mode that supports granular reason codes.
Server mode: The Node.js server calls the Finesse REST API directly using a supervisor Basic Auth token (PUT /finesse/api/User/:id). This mode requires no gadget configuration but is limited to setting READY or a generic "Supervisor Initiated" NOT_READY — it cannot assign specific reason codes like "Webex DND" or "Webex Meeting".
To get started, a developer needs:
- A Webex Bot token (created at developer.webex.com)
- A Cisco Finesse server (UCCX or UCCE) with admin and supervisor Basic Auth credentials
- Four NOT_READY reason codes pre-created in Unified CCE Management: "Webex DND", "Webex Meeting", "Webex Call", "Webex Unavailable"
- Node.js v21.5+ (or Docker) and a publicly accessible HTTPS endpoint for the server
- The Finesse agent email addresses must follow the pattern: finesseLoginName@your-domain
Preview listing
This App Hub entry was published from an open pull request. Review the change.
Support
Third-Party Tool
Cisco Finesse
Estimated Implementation Time
4-8 hours
Categories
This Playbook shows how to build an integration that automatically mirrors a Webex user's real-time presence state into their Cisco Finesse (UCCX/UCCE) agent status, eliminating the manual step of toggling Finesse between READY and NOT_READY when agents join Webex calls or meetings.
The integration is a Node.js server that uses a Webex Bot token to subscribe to presence events via the Webex Mercury WebSocket. When a monitored agent's Webex presence changes, the server maps the Webex presence state to a Finesse agent state and applies it automatically. Five Webex presence states trigger a Finesse NOT_READY transition:
- Do Not Disturb (reason code: "Webex DND")
- Active Webex Call (reason code: "Webex Call")
- Active Webex Meeting (reason code: "Webex Meeting")
- Presenting in a Webex Meeting (reason code: "Webex Meeting")
- Unknown/Unavailable (reason code: "Webex Unavailable")
When the Webex presence clears, the agent is automatically returned to READY.
Two operating modes are provided:
Gadget mode (recommended): The server pushes presence updates to a Finesse XML gadget running in the agent's desktop browser via Socket.io. The gadget calls the Finesse client-side JavaScript API (user.setState) to set the agent's own status, including the specific NOT_READY reason code. This mode requires adding a gadget entry to the Finesse desktop layout and is the only mode that supports granular reason codes.
Server mode: The Node.js server calls the Finesse REST API directly using a supervisor Basic Auth token (PUT /finesse/api/User/:id). This mode requires no gadget configuration but is limited to setting READY or a generic "Supervisor Initiated" NOT_READY — it cannot assign specific reason codes like "Webex DND" or "Webex Meeting".
To get started, a developer needs:
- A Webex Bot token (created at developer.webex.com)
- A Cisco Finesse server (UCCX or UCCE) with admin and supervisor Basic Auth credentials
- Four NOT_READY reason codes pre-created in Unified CCE Management: "Webex DND", "Webex Meeting", "Webex Call", "Webex Unavailable"
- Node.js v21.5+ (or Docker) and a publicly accessible HTTPS endpoint for the server
- The Finesse agent email addresses must follow the pattern: finesseLoginName@your-domain
Preview listing
This App Hub entry was published from an open pull request. Review the change.
