Building a Custom Agent Desktop UI using the Embeddable Framework

How-To-Articles
1

Building a Custom Agent Desktop UI using the Embeddable Framework

Executive Summary & Architectural Context

While the native Genesys Cloud web interface (apps.mypurecloud.com) is robust, many enterprise contact centers prefer to keep agents inside their primary CRM (Salesforce, Zendesk, Dynamics 365, or a proprietary homegrown app). Forcing agents to “alt-tab” between a CRM window and the Genesys Cloud window ruins Average Handle Time (AHT) and fragments the customer context.

The architectural solution is the Genesys Cloud Embeddable Framework. This allows developers to embed a fully functional, miniaturized Genesys Cloud softphone directly into a custom web application via an <iframe>. More importantly, it provides a bidirectional JavaScript API, allowing your custom app to control the softphone (e.g., click-to-dial) and allowing the softphone to command your app (e.g., screen-pop a customer profile on incoming call).

This masterclass details how to initialize the Embeddable Framework, subscribe to interaction events, and trigger automated CRM lookups using the subscribe API.

Prerequisites, Roles & Licensing

  • Licensing: Available on all Genesys Cloud CX tiers.
  • Roles & Permissions: None required for the agent beyond standard ACD permissions.
  • Platform Dependencies:
    • A host web application (HTML/JS) running on a secure https:// domain.

The Implementation Deep-Dive

1. Embedding the IFrame

The foundation of the framework is simply embedding the pre-built UI into your web app.

  1. Open your host application’s HTML.
  2. Insert the iframe pointing to your specific Genesys Cloud region.
<iframe id="genesys-cloud-softphone" 
        src="https://apps.mypurecloud.com/crm/index.html" 
        allow="camera; microphone; autoplay; clipboard-write">
</iframe>

Crucial: You must include the allow="microphone" directive, or the browser will silently block WebRTC audio, resulting in immediate call failures.

2. Initializing the Framework.js SDK

You cannot control the iframe with raw DOM manipulation due to Cross-Origin Resource Sharing (CORS) security. You must use the official framework.js SDK.

  1. In your host application, create a framework.js file.
  2. Define the global window.Framework object.
window.Framework = {
    config: {
        name: "MyCustomCRM",
        clientIds: { "mypurecloud.com": "YOUR_OAUTH_CLIENT_ID" },
        settings: {
            embedWebRTCByDefault: true,
            hideWebRTCPopUpOption: true,
            enableCallLogs: true
        }
    },
    initialSetup: function () {
        console.log("Embeddable Framework Initialized!");
        setupEventSubscribers();
    }
};

3. Subscribing to Interaction Events (Screen-Pops)

The most common requirement is popping a customer profile when the phone rings.

  1. Inside your setupEventSubscribers() function, use the window.PureCloud.subscribe method to listen to the Interaction object.
function setupEventSubscribers() {
    window.PureCloud.subscribe([
        {
            type: 'Interaction',
            callback: function (category, interaction) {
                // Check if it's an inbound voice call ringing
                if (interaction.state === 'ALERTING' && interaction.isInternal === false) {
                    
                    const callerId = interaction.ani;
                    console.log(`Incoming call from: ${callerId}`);
                    
                    // Call your custom CRM function to search for the phone number
                    myCrmApp.searchAndPopProfile(callerId);
                }
            }
        }
    ]);
}

4. Sending Commands to the Softphone (Click-to-Dial)

If an agent clicks a phone number inside your custom CRM, you want the iframe to instantly dial it.

  1. Attach an event listener to the phone number links in your CRM.
  2. When clicked, use the window.PureCloud.clickToDial method.
function makeOutboundCall(phoneNumber) {
    window.PureCloud.clickToDial({
        number: phoneNumber,
        autoPlace: true
    });
}

Validation, Edge Cases & Troubleshooting

Edge Case 1: OAuth and 3rd-Party Cookie Blocks

Because the Embeddable Framework runs in an iframe on mypurecloud.com while your CRM runs on mycompany.com, browsers like Chrome and Safari will aggressively block the iframe’s authentication cookies (ITP - Intelligent Tracking Prevention).

  • The Trap: The agent will be trapped in an infinite login loop, repeatedly entering their credentials but never actually signing in.
  • Solution: The Embeddable Framework supports a dedicated popup authentication flow to bypass third-party cookie blocks. Ensure dedicatedLoginWindow: true is set in your framework.js configuration.

Edge Case 2: Populating the Call Log (Dispositioning)

If your CRM requires agents to write call notes (dispositions), you do not want them typing notes in the Genesys iframe and the CRM.

  • Solution: Hide the native Genesys Wrap-up UI. Use the Framework API to listen for the Interaction.state === 'DISCONNECTED' event. When triggered, open a custom form in your CRM. Once the agent clicks “Save” in your CRM, use the window.PureCloud.setWrapup API method to push the selected wrap-code back into the Genesys Cloud analytics database.

Official References