Genesys Cloud - Main

Hi All,

Can someone please assist me with setting up the Private Embeddable Framework on my local system to test it with Web Messaging?

My goal is to set up and access both the embedded client and the Web Messaging chat widget locally, allowing me to test the functionality from both the agent and customer perspectives.

Thank You

Hi Narasimha

This is very doable locally. The trick is that "Private Embeddable Framework" and "local testing" are actually two slightly different modes, and you want to start in local mode before you upload anything to the org. Here's the sequence I'd follow.

Prerequisites

• An OAuth client in your org. The Genesys sample uses the Token Implicit Grant (Browser) grant type, but note implicit grant is being retired. The Developer Center now has a guide on migrating the Embeddable Framework to PKCE, so if this is a greenfield build, go straight to Code Authorization with PKCE. GitHub
• Node.js + Git.
• A published inbound message flow, a queue, and an agent account you can put On Queue.

Part 1 - Embeddable Framework on localhost

1. Clone MyPureCloud/purecloud-embeddable-framework-example and run npm install.
2. Edit example.html and point the iframe URL at the correct region for your org, the local-testing form is https://apps.<your-region>/crm/index.html?crm=framework-local-secure, which tells the embedded client to load your framework.js from https://localhost. This pattern works with the framework.js hosted locally and gives you full control of interactions and agent status from the iframe. - GitHubGenesys Cloud Developer
3. Edit framework.js and add your Client ID under the clientIds entry matching your org's region. GitHub
4. Run node server.js (elevated on Windows, sudo on macOS - it binds 443), then browse to https://localhost/example.html and log in. GitHub

Also check Admin → Organization Settings → Security & Compliance. If "Restrict Genesys Cloud Embedding" is enabled, https://localhost has to be in the Allowed Embeddable Domain(s) list or the iframe will be blocked by the CSP frame-ancestors directive. Genesys

Part 2 - moving to a true private deployment

Once the local version behaves, go to Admin → Integrations, add a Private Genesys Cloud Embeddable Framework integration, upload the same framework.js, restrict it to a group if you want, and toggle it Active. Then swap the iframe src to the private-deployment URL from the iframe URLs table in the Developer Center. Be aware of caching - after uploading a new framework.js you need to refresh the client, and changes can take a few minutes to show. You can have up to five implementations in one org, which is handy for keeping a dev and a prod variant side by side. Genesys + 2

Part 3 - the customer side (Messenger)

1. Admin → Message → Messenger Configurations: build a config and save it as a version.
2. Messenger Deployments: create a deployment, assign that config version, and select a published inbound message flow under "Select your Architect Flow.  If no flow is selected, messaging functions won't be available. Genesys
3. For domain restriction, choose "Allow all domains", which is the intended option for testing and development. Trying to whitelist localhost explicitly is where most people get stuck. Genesys
4. Copy the snippet into a plain HTML page and serve it from a different origin to the framework page - e.g. a second local server on port 8443. Don't open it via file://.

Take note of the following when testing

Run the customer page in a separate browser profile (or a different browser entirely) from the one holding your agent session. Same-browser testing gives you odd session behaviour and you won't get a clean anonymous visitor. And per the Genesys warning, don't have another embedded client variant running at the same time.  Chrome/Firefox extension, Salesforce, Teams, as it causes strange behaviour with interaction logs and WebRTC phones. Genesys

Hope this helps

Regards

HI Stephan,

Thank you so much. This is really helpful, and I appreciate your assistance.