Messages Reference

The CFC SDK uses a typed postMessage protocol for communication between the CFC iframe and the host application. All messages extend BaseMessage:

interface BaseMessage {
	type: string;
	messageId: string; // Auto-generated UUID
}

TIP

The SDK handles all these messages automatically. You don't need to listen for them manually — just provide callbacks in the CfcClientConfig. This page is a reference for understanding the protocol.

CFC to Host Messages

These messages are sent from the CFC iframe to the host application.

LOADED

Emitted when CFC has finished loading and is ready for interaction. The SDK automatically sends DIMENSIONS_CHANGED in response and calls onLoaded.

interface LoadedMessage extends BaseMessage {
	type: "LOADED";
}

---

NAVIGATED_TO_TARGET

Emitted when CFC navigates to a new page internally. The SDK calls onNavigated.

interface NavigatedToTargetMessage extends BaseMessage {
	type: "NAVIGATED_TO_TARGET";
	target: string;
	targetAction?: string;
}

Field	Type	Description
target	string	The navigation target path (e.g., '/view-payments')
targetAction	string | undefined	Optional action (e.g., 'schedulePaymentSuccess')

---

CONTENT_SIZE_CHANGE

Emitted when CFC content dimensions change. The SDK automatically resizes the iframe.

interface ContentSizeChangeMessage extends BaseMessage {
	type: "CONTENT_SIZE_CHANGE";
	height: number;
	width?: number;
}

Field	Type	Description
height	number	Content height in pixels
width	number | undefined	Content width in pixels (optional)

---

SCROLL_TO

Emitted when CFC requests the host to scroll. The SDK handles this automatically.

interface ScrollToMessage extends BaseMessage {
	type: "SCROLL_TO";
	relativeScrollX?: number;
	relativeScrollY?: number;
	preventScroll?: boolean;
}

Field	Type	Description
relativeScrollX	number | undefined	Horizontal scroll offset relative to iframe
relativeScrollY	number | undefined	Vertical scroll offset relative to iframe
preventScroll	boolean | undefined	When true, lock host scrolling (e.g., modal open)

---

EXIT_REQUESTED

Emitted when the user wants to leave the CFC experience. Calls onExitRequested.

interface ExitRequestedMessage extends BaseMessage {
	type: "EXIT_REQUESTED";
	originator: string;
}

Field	Type	Description
originator	string	Identifier for what triggered the exit

---

AUTHENTICATION_ERROR

Emitted when CFC encounters an authentication problem. Calls onAuthenticationError.

interface AuthenticationErrorMessage extends BaseMessage {
	type: "AUTHENTICATION_ERROR";
	reason: AuthErrorReason;
	message: string;
}

Field	Type	Description
reason	AuthErrorReason	Error reason code (see Error Handling)
message	string	Human-readable error description

---

SESSION_EXPIRED

Emitted when the CFC session has expired. Calls onSessionExpired.

interface SessionExpiredMessage extends BaseMessage {
	type: "SESSION_EXPIRED";
}

---

USER_ACTIVE_PING

Emitted periodically when the user is actively interacting with CFC. Calls onUserActivePing.

interface UserActivePingMessage extends BaseMessage {
	type: "USER_ACTIVE_PING";
}

---

SUBSCRIPTION_UPGRADE_REQUEST

Emitted when a CFC feature requires a subscription upgrade. Calls onUpgradeRequest.

interface SubscriptionUpgradeRequestMessage extends BaseMessage {
	type: "SUBSCRIPTION_UPGRADE_REQUEST";
	featureName: string;
	returnUrl: string;
}

Field	Type	Description
featureName	string	The feature that requires an upgrade
returnUrl	string	URL to return to after the upgrade flow

See Subscription Management for the full flow.

---

DOWNLOAD_FILE

Emitted when a file download is triggered in native mobile mode (isMobileApp: true). Calls onDownloadFile.

interface DownloadFileMessage extends BaseMessage {
	type: "DOWNLOAD_FILE";
	fileName: string;
	data: string;
}

Field	Type	Description
fileName	string	Name of the file being downloaded
data	string	Base64-encoded file content

See Mobile Native Integration for the full flow.

---

Host to CFC Messages

These messages are sent from the host application to the CFC iframe. The SDK sends most of these automatically.

NAVIGATE_REQUEST

Request CFC to navigate to a specific target. Use client.navigateTo():

import { NavigationTarget } from "@melio-eng/cfc-sdk";

client.navigateTo(NavigationTarget.VIEW_PAYMENTS);
client.navigateTo(NavigationTarget.viewBill("bill-123"));

interface NavigateRequestMessage extends BaseMessage {
	type: "NAVIGATE_REQUEST";
	target: string;
}

---

USER_SCROLL

Sent automatically by the SDK on every host scroll event.

interface UserScrollMessage extends BaseMessage {
	type: "USER_SCROLL";
	scrollX: number;
	scrollY: number;
}

---

DIMENSIONS_CHANGED

Sent automatically by the SDK on load, resize, and visual viewport change.

interface DimensionsChangedMessage extends BaseMessage {
	type: "DIMENSIONS_CHANGED";
	windowHeight: number;
	windowWidth: number;
	elementDistanceFromTop: number;
	elementDistanceFromLeft: number;
	visualViewportHeight?: number;
	visualViewportWidth?: number;
	minimumContentHeight?: number;
}

Field	Type	Description
windowHeight	number	window.innerHeight
windowWidth	number	window.innerWidth
elementDistanceFromTop	number	Iframe top offset from document top
elementDistanceFromLeft	number	Iframe left offset from document left
visualViewportHeight	number | undefined	Visual viewport height (accounts for mobile keyboard)
visualViewportWidth	number | undefined	Visual viewport width
minimumContentHeight	number | undefined	Optional minimum height hint

---

SUBSCRIPTION_UPGRADE_FINISHED

Inform CFC that a subscription upgrade flow has completed. Use client.sendSubscriptionUpgradeFinished():

client.sendSubscriptionUpgradeFinished(true); // upgraded
client.sendSubscriptionUpgradeFinished(false); // cancelled

interface SubscriptionUpgradeFinishedMessage extends BaseMessage {
	type: "SUBSCRIPTION_UPGRADE_FINISHED";
	wasUpgraded: boolean;
}

Union Types

The SDK exports discriminated union types for type-safe message handling:

// All CFC -> Host message types
type CfcMessage = NavigatedToTargetMessage | LoadedMessage | ContentSizeChangeMessage | ScrollToMessage | ExitRequestedMessage | AuthenticationErrorMessage | SessionExpiredMessage | UserActivePingMessage | SubscriptionUpgradeRequestMessage;

// All Host -> CFC message types
type HostMessage = NavigateRequestMessage | UserScrollMessage | DimensionsChangedMessage | SubscriptionUpgradeFinishedMessage;

MessageType Constants

Use MessageType for autocomplete-friendly access to all message type strings. For more precise typing, use IncomingMessageType (CFC to Host) or OutgoingMessageType (Host to CFC):

import { MessageType, IncomingMessageType, OutgoingMessageType } from "@melio-eng/cfc-sdk";

// All message types
MessageType.LOADED; // 'LOADED'
MessageType.NAVIGATE_REQUEST; // 'NAVIGATE_REQUEST'

// Only CFC -> Host messages
IncomingMessageType.LOADED; // 'LOADED'
IncomingMessageType.CONTENT_SIZE_CHANGE; // 'CONTENT_SIZE_CHANGE'
IncomingMessageType.NAVIGATED_TO_TARGET; // 'NAVIGATED_TO_TARGET'

// Only Host -> CFC messages
OutgoingMessageType.NAVIGATE_REQUEST; // 'NAVIGATE_REQUEST'
OutgoingMessageType.DIMENSIONS_CHANGED; // 'DIMENSIONS_CHANGED'