Skip to content

UCP CRM Iframe Communication

Overview

This document describes the communication protocol between UCP and embedded CRM iframes using the postMessage API. This allows CRM applications loaded within UCP tabs to send commands back to the parent UCP application.

How It Works

UCP renders CRM pages inside iframes within the CRM tabs section. These iframes can communicate with UCP by sending messages using the browser's postMessage API. UCP listens for these messages and performs the corresponding actions.

Sending Messages from the Iframe

From within the CRM iframe, use the following pattern to send messages to UCP:

window.parent.postMessage({
  type: 'EVENT_TYPE',
  payload: { /* optional data */ }
}, '*')

Parameters

  • type (string, required): The event type identifier. UCP uses this to determine which action to perform.
  • payload (object, optional): Additional data required for the event.

Supported Events

Event: CLOSE_CRM_TAB

Closes the CRM tab that sent the message. The iframe does not need to know its own tab ID; UCP automatically identifies the source iframe and closes the corresponding tab.

Fields

  • type (string): Must be "CLOSE_CRM_TAB".
  • payload (object, optional): Can optionally include an id field if the tab ID is known.

Example (Automatic Identification)

// The iframe simply sends this message
// UCP will identify which tab to close automatically
window.parent.postMessage({
  type: 'CLOSE_CRM_TAB'
}, '*')

Example (With Explicit ID)

// If you know the tab ID, you can provide it directly
window.parent.postMessage({
  type: 'CLOSE_CRM_TAB',
  payload: {
    id: '550e8400-e29b-41d4-a716-446655440000'
  }
}, '*')

How It Works

  1. UCP receives the CLOSE_CRM_TAB message.
  2. If payload.id is provided, UCP closes the tab with that ID directly.
  3. If no ID is provided, UCP:
  4. Queries all iframes within #iframe-parent
  5. Compares each iframe's contentWindow with the message source
  6. Finds the matching tab by URL and closes it

Event: MAKE_CALL

Initiates an outbound call from UCP.

Fields

  • type (string): Must be "MAKE_CALL".
  • payload (object, required): Contains the call destination.

payload object

  • destination (string): The phone number or extension to call. Non-numeric characters are automatically stripped.

Example

window.parent.postMessage({
  type: 'MAKE_CALL',
  payload: {
    destination: '+1 (555) 123-4567'
  }
}, '*')

Security Considerations

  • Messages are accepted from any origin ('*'). Ensure your CRM application validates the parent context if needed.
  • UCP validates message structure before processing (requires type field).
  • Tab identification uses contentWindow comparison, which is secure within the same browser context.

Message Flow Overview

┌─────────────────┐                    ┌─────────────────┐
│   CRM Iframe    │                    │       UCP       │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │  postMessage({ type: 'CLOSE_CRM_TAB' })
         │─────────────────────────────────────>│
         │                                      │
         │                          Identify iframe source
         │                          Find matching tab
         │                          Close tab
         │                                      │
         │              Tab closed              │
         │<─────────────────────────────────────│
         │                                      │

Implementation Details

UCP Components

  • CRMListener (/containers/crm/CRMListener.jsx): Dedicated component that listens for messages from CRM iframes.
  • Listener (/containers/listener/Listener.jsx): General message listener for other events like MAKE_CALL.

Tab ID Format

Tab IDs are UUID v4 strings generated when a new CRM tab is created:

xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479