This document outlines how to embed Regal into your web platform, providing agents with a seamless way to handle calls, sms and other workflows from within their existing toolkit. By embedding Regal as an iFrame, agents can access Regal’s core functionality without leaving their primary platform, creating a more efficient "single pane of glass" experience.

📘

Who is this option best for?

Regal's universal embeddable iFrame is best for support agents already using a homegrown or 3rd party ticketing system or CRM that houses the key customer information and operational actions they need to access. The embeddable iFrame does not contain the full agent functionality available in Regal, only the subset of functionality sufficient for these agents.

Sales and other outbound agents are not advised to use this option. Using Regal as their main desktop - with full access to Regal's unified profile, campaign information, and custom contact lists - will lead to a better agent experience and better business outcomes. Additionally, support agents who are not happy with their current platform may also benefit from using Regal as their main desktop, and simply having the other platform open in another tab. Regal can automatically pop the relevant record of that platform to maintain agent efficiency.

The widget offers native support for features like click-to-dial and changing an agent's availability status. Additionally, Regal sends events (e.g., agent placed a call, agent was assigned a task) that you can act on in your platform, for example, surface relevant context to the agent about the contact or conversation.

For platforms with native support—like Salesforce, Kustomer, and Retool—the integration is plug-and-play. For all other web platforms, you can integrate Regal with a small custom implementation following the documentation below.

DEMO VIDEO

Setup

Step 1

In order to embed Regal into your platform, email [email protected] with the list of domains your platform operates on. This step is necessary to ensure that we can allow these domains in our content security policies; otherwise, Regal will not load on your site.

Step 2

Add an iFrame in your platform pointing to the Regal app: https://app.regal.io. Make sure you include the allow directive on the iFrame with at least these values: allow="microphone; clipboard-read; clipboard-write".

You can check our code snippets below for reference. At this point, if Step 1 and Step 2 have been completed, Regal should be running within your platform!

Step 3

Now it's time to set up the interaction between Regal and your platform. iFrames communicate through the window's postMessage function. You can communicate with Regal in two directions: posting messages to the Regal iFrame, and receiving messages from the Regal iFrame. Our sample snippets can help visualize a basic example of how to set up this bidirectional communication.

What can Regal's Embeddable iFrame do?

While working with an embedded version of Regal, there are two categories of supported interactions:

Events: Consider this the outbound flow. These are actions that the user takes in the Regal application that will emit an event which can be captured by your platform and acted upon. Examples include changing the current status or accepting a task.

Actions: This would be considered the inbound flow. Your platform notifies the Regal app that it needs to perform a certain action. Examples include making an outbound call or changing the agent's status.
All of these interactions are powered by messages sent back and forth between your platform and the Regal iFrame via javascript. Messages have a predefined structure that needs to be fulfilled for these interactions to work as expected.

Events

Regal sends the following events:

Actions

Regal supports the following actions:

Sizing Guidelines

Depending on the functionality you want to expose to your agents using the Regal iFrame, we recommend using the sizing guidelines below.

Full

Medium

Small

Sample Code Snippets

Here are sample code snippets for React and JavaScript.

function App() {
    const iframeRef = useRef<HTMLIFrameElement>(null);

    // send Actions to Regal
    function becomeAvailable() {
        const message = {
            source: "my-platform",
            action: "change-status",
            status: "Available",
        };
        iframeRef.current?.contentWindow?.postMessage(message);
    }

    // listen for Regal Events
    useEffect(() => {
      function handler (event: MessageEvent) {
        const { data, source } = event;
        if (source === iframeRef.current?.contentWindow) {
          // received a message from the Regal iframe
          const { action, source } = data;
          if (source !== "regal") {
              // not from the Regal app, ignoring
              return;
          }
          switch (action) {
              case "task-active":
              case "task-assigned":
              case "task-accepted":
              case "task-cancelled":
              case "task-completed":
              case "task-wrapping":
              case "status-changed":
              case "started-barging":
              case "started-listening":
                  // handle any of these cases separately
                  // you can trigger any desired actions in your platform
                  break;
              default:
                  console.log("unsupported action", action);
          }
        }
      }
      window.addEventListener("message", handler);
      return () => window.removeEventListener("message", handler);
    }, []);

    return (
        <div>
            <iframe
                ref={iframeRef}
                id="regal-frame"
                src="https://app.regal.io"
                allow="microphone; fullscreen; clipboard-read; clipboard-write"
            ></iframe>
            <div>
                <button onClick={becomeAvailable}> Click to Become Available </button>
            </div>
        </div>
    );
}

//send Actions to Regal
const regalIframe = document.getElementById("regal-frame");
if (regalIframe) {
    const message = {
        source: "my-platform",
        action: "change-status",
        status: "Available",
    };
    regalIframe.contentWindow.postMessage(message);
}

// receive Events from Regal
function handler (event: MessageEvent) {
  const { data, source } = event;
  if (source === regalIframe.contentWindow) {
    // received a message from the Regal iframe
    const { action, source } = data;
    if (source !== "regal") {
        // not from the Regal app, ignoring
        return;
    }
    switch (action) {
        case "task-active":
        case "task-assigned":
        case "task-accepted":
        case "task-cancelled":
        case "task-completed":
        case "task-wrapping":
        case "status-changed":
        case "started-barging":
        case "started-listening":
            // handle any of these cases separately
            // you can trigger any desired actions in your platform
            break;
        default:
            console.log("unsupported action", action);
    }
  }
}
window.addEventListener("message", handler);