Implementing Custom CRM Integrations Using the Genesys Cloud Embeddable Framework SDK

How-To-Articles
1

Implementing Custom CRM Integrations Using the Genesys Cloud Embeddable Framework SDK

Executive Summary & Architectural Context

In many specialized industries-such as healthcare logistics, boutique law firms, or niche manufacturing-the primary CRM is not Salesforce or ServiceNow. It is a custom-built, industry-specific web application or a legacy database that lacks a pre-built “Marketplace” integration. For an agent, this results in the “Tab-Tango”: every time a call arrives, they must manually highlight the caller’s ANI from their softphone, copy it, alt-tab to the CRM, click the search bar, paste the number, and hit “Enter.” To make an outbound call, they have to reverse the process. This manual context-switching adds 30-40 seconds of silent friction to every interaction, frustrating the agent and making the customer wait in silence.

A Principal Architect solves this by using the Genesys Cloud Embeddable Framework. Instead of making the agent go to the softphone, you bring the softphone into the CRM. The Embeddable Framework is a lightweight, customizable version of the Genesys Cloud interface that lives inside an iframe within your host application. It provides a robust SDK that allows the CRM and the softphone to “Talk” to each other, enabling automated screen-pops, one-click dialing, and background data synchronization.

This masterclass details how to architect and deploy a custom integration using the Embeddable Framework SDK, eliminating the “Tab-Tango” and streamlining the agent workflow.

Prerequisites, Roles & Licensing

Licensing & Permissions

  • Licensing Tier: Genesys Cloud CX 1, 2, or 3.
  • Granular Permissions:
    • Administration > Integrations > View, Add, Edit
    • User > Agent > View
  • Dependencies:
    • Host CRM: Must be a web-based application capable of hosting an iframe.
    • HTTPS: Both the CRM and the integration files must be served over HTTPS.

The Implementation Deep-Dive

1. The Architectural Strategy: The iframe Bridge

The Embeddable Framework works by loading a specific Genesys URL (apps.mypurecloud.com/crm/index.html) inside an iframe. To make it “Smart,” you provide a framework.js file that the Genesys iframe pulls from your server.

The Workflow:

  1. The Handshake: The host CRM loads the iframe.
  2. The Script Injection: The iframe loads your framework.js file.
  3. The Communication: Your framework.js uses the SDK to listen for Genesys events (like “Call Started”) and uses window.postMessage to tell the CRM to “Search for this User.”

2. Implementing the framework.js Configuration

This file is the “Brain” of your integration. It defines how the softphone behaves and how it interacts with the host.

window.Framework = {
    config: {
        name: "MyCustomCRMIntegration",
        clientIds: {
            "mypurecloud.com": "your-oauth-client-id"
        },
        settings: {
            embedWebPages: true,
            hideWebPages: false,
            enableCallLogs: true
        }
    },

    // 1. Initializing the SDK
    initialSetup: function () {
        console.log("Embeddable Framework Initialized");
        
        // Subscribe to Interaction Events
        window.PureCloud.subscribe([
            { type: "Interaction", callback: this.onInteractionEvent.bind(this) }
        ]);
    },

    // 2. The Screen-Pop Trigger
    onInteractionEvent: function (event) {
        if (event.category === "add" && event.type === "call") {
            const ani = event.interaction.ani;
            // Send a message to the Parent Window (the CRM)
            window.parent.postMessage({
                type: "SCREEN_POP",
                phoneNumber: ani
            }, "*");
        }
    }
};

3. The Host-Side Listener (The CRM)

The CRM must be “Listening” for the message sent by the framework.js.

window.addEventListener("message", (event) => {
    if (event.data.type === "SCREEN_POP") {
        const phone = event.data.phoneNumber;
        // Trigger the CRM's internal search function
        myCRMSearch(phone);
    }
}, false);

[!IMPORTANT]
Architectural Reasoning: By using window.postMessage, you maintain a strict security boundary. The Genesys iframe never has direct access to the CRM’s DOM or database, preventing “Cross-Site Scripting” (XSS) risks while still allowing the two applications to collaborate seamlessly.

“The Trap”: The “Double-Pop” Chaos

The Scenario: You have a busy agent who is already handling a chat interaction. A new voice call arrives.

The Catastrophe: If your framework.js is naively programmed to trigger a screen-pop for every “add” event, the CRM will suddenly navigate away from the chat customer’s record to the new caller’s record. The agent loses their chat notes, the chat customer’s context is gone, and the agent is left confused. This “Focus Theft” is a major driver of agent frustration in multi-channel environments.

The Principal Architect’s Solution: The “Interaction State” Guard

  1. Check Focus: Before triggering a postMessage, check the isFocused or state attribute of the interaction.
  2. Logic: Only trigger a screen-pop if the interaction is the Active Primary interaction or if the agent is currently on a “Home” screen.
  3. The “Soft-Pop” Pattern: Instead of a hard redirect, have the CRM display a small notification badge: “New Call from John Doe. [Click to Open Record]”. This gives the agent control over their workspace.

Advanced: Click-to-Dial via the SDK

The Embeddable Framework allows the CRM to “Push” a phone number to the softphone for immediate dialing.

Implementation Detail:
In the CRM, add a click handler to phone numbers:

function callCustomer(phoneNumber) {
    const iframe = document.getElementById("genesys-softphone-iframe");
    iframe.contentWindow.postMessage({
        type: "clickToDial",
        data: { number: phoneNumber, autoPlace: true }
    }, "https://apps.mypurecloud.com");
}

This eliminates the “Copy-Paste” step entirely, turning a 5-second task into a 100ms click.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Content Security Policy (CSP) Blockers

The failure condition: The softphone loads, but your framework.js fails to load or the postMessage is blocked.
The root cause: The CRM’s web server has a strict Content-Security-Policy header that forbids loading scripts from external domains or embedding iframes.
The solution: You must update the CRM’s web server configuration to include frame-src https://*.mypurecloud.com and script-src for your framework hosting domain. Without these, the browser’s security engine will kill the integration before it starts.

Edge Case 2: Handling Multiple “PureCloud” Tabs

The failure condition: The agent has the CRM open in one tab and the standard Genesys Cloud UI open in another.
The root cause: Token collisions and event duplication.
The solution: The Embeddable Framework is designed to be the primary interface. Advise agents to close the standalone Genesys tab. If both are needed, use a Global Client ID and implement “Leader Election” logic in your JS to ensure only one tab reacts to incoming events.

Reporting & ROI Analysis

The success of a custom CRM integration is measured by Efficiency Gains.

Metrics to Monitor:

  • Initial AHT Segment: Has the time from “Answer” to “First meaningful note” decreased?
  • Click-to-Dial Adoption: Percentage of outbound calls made via the CRM vs. manual dialing.
  • Agent Satisfaction (eSPS): Qualitative feedback on the reduction of “Tab-Tango” friction.

Target ROI: Expect a 15-20% reduction in total AHT for businesses with heavy CRM usage and a significant improvement in data accuracy as agents are always looking at the correct customer record.

Official References