Cleaning up Genesys Cloud agent scripts with a Function

Over time, Genesys Cloud agent scripts grow more and more complex. Past a certain point, refactoring them through the graphical interface becomes tedious: it’s hard to tell which variables and actions are still actually used, and which are nothing but dead weight.

This article describes a small tool to automate that diagnosis, deployed as a Genesys Cloud Function so it’s available at any time, with no infrastructure to maintain.

💡 The full code is available on my GitHub: github.com/antoningar/genesyscloud-script-cleaner. You can clone it and deploy it in your own org.

The problem: dead weight in scripts

An agent script lives a long time: variables, custom actions and conditional branches get added as business needs evolve. But what’s no longer used is rarely removed, because the graphical interface doesn’t tell you which objects have become orphaned. The result: bloated scripts that are harder to read, maintain and extend.

The principle: analyzing the script’s JSON

Under the hood, a Genesys Cloud agent script is a JSON document describing its customActions and variables. The tool retrieves that representation, analyzes it, and deduces what is never actually referenced.

1. Fetch the script — the function receives a script_id and OAuth credentials (client credentials). Through the purecloud-platform-client-v2 SDK, it triggers a script export (postScriptExport), retrieves the download URL and downloads the JSON.
2. Analyze the structure — the JSON is parsed to extract the list of custom actions and variables, each identified by a unique id.
3. Detect unused objects — for each action or variable, the occurrences of its id in the raw script content are counted. If the id appears only once, only its definition exists: the object is never used.
4. Handle transitive dependencies — an object may only be referenced by other objects that are themselves unused. The tool catches these cases: an action only called from a dead action, or a variable only read inside a dead variable, is also considered unused.
5. Return the list — the function returns the consolidated list of unused variables and actions, with their name and type.

Why a Genesys Cloud Function

Rather than a script to run from a workstation, the logic is packaged as a Genesys Cloud Function: a serverless handler (Lambda model) that receives the script_id in the event and the OAuth credentials in the clientContext. The analysis becomes an on-demand service, embeddable in any process, with nothing to install or host.

The handler validates the inputs (presence of script_id and credentials), runs the analysis and returns a clean HTTP result: 400 if the request is malformed, 500 on an internal error, 200 with the list of unused objects otherwise.

Technical stack

• Genesys Cloud Functions (serverless handler, AWS Lambda model)
• TypeScript for all the business logic
• purecloud-platform-client-v2 SDK (ScriptsApi, client credentials grant authentication) for the script export
• BDD tests with Cucumber, lint and build verified in GitHub Actions CI

The sample on GitHub

The complete code of the function is available open source: github.com/antoningar/genesyscloud-script-cleaner. The repository contains the handler, the analysis logic, the tests and the instructions to test it locally or deploy it as a Genesys Cloud Function.

Going further

Native asynchronous workflows on Genesys Cloud
Infrastructure as Code
About me
My work