ReelFlow Player API Reference

Core Concepts

You will see us refer to Flows in this guide. Flows are the choose-your-own-adventure video experiences that are presented in the ReelFlow Player. The Flow is advanced and explored by the visitor using the configurable Action Buttons. Flows can be built and managed directly, in the ReelFlow Flow Builder.

A Flow can be configured to use one of two Player types:

• Overlay - an interactive video experience that floats in the corner of the screen, over existing page content
  • The Overlay player is hidden by default, and is launched from a smaller floating video preview on a loop called an Eye-catcher, or can be programmatically launched

• Inline - an interactive video experience that sits inline amongst content
  • The Inline player is visible by default, and unlike the Overlay player does not have an Eye-catcher component or need to be launched, but can be set to auto-play.

An instance of the ReelFlow Player therefore may consist of these key components:

• Eye-catcher - to launch the Flow (Overlay players only, optional)
• Player - the video player with all controls and user-configurable Action Buttons
• Flow - the interactive Steps, video content and Action Buttons within the Player

The ReelFlow experience is always injected into the page, which means customers are not required to edit the HTML of the page to enjoy publishing Flows. We therefore do not offer a HTML embed code per-Player. 

Getting Started

As long as the Install Code is already added and verified working on your website (check from the Dashboard at Settings > Install Code), the Player API is available for you to use.

Initialising & accessing the ReelFlow Object

We use the defer attribute, which means the ReelFlow Player is loaded asynchronously.

You therefore should wait for the reelflow:ready event:

window.addEventListener('reelflow:ready', () => {
    // ReelFlow object is now available and initialized
    var targetFlow = ReelFlow.getFlow("F-123456ABCD");
    
    // Overlay Flows only. Inline Flows don't have player.show()
    targetFlow.player.show();
});

Configuring with ReelFlowSettings

window.ReelFlowSettings is an optional configuration object.

Define it in a <script> tag before the ReelFlow Install Code. If it’s defined after, it has no effect.

It supports one property, disabledEyeCatchers.

Disable the Eye-catcher on every Overlay Flow published on the page:

<script>
  window.ReelFlowSettings = { disabledEyeCatchers: '*' };
</script>
<!-- ReelFlow Install Code goes below -->

Disable it on specific Flows only:

<script>
  window.ReelFlowSettings = {
    disabledEyeCatchers: ['F-123456ABCD', 'F-987654WXYZ'],
  };
</script>

The value must be '*' or an array of Flow codes. A single string such as 'F-123456ABCD' is ignored. See Suppressing the Eye-catcher below for how this works alongside the Activation tab setting.

Interacting with a specific flow

Flow IDs can be found in the Flow Builder, and will look something like this: F-123456ABCD.

// Get Flow instance with ID  'F-123456ABCD'
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.show()
ReelFlow.getFlow('F-123456ABCD').player.on(/* ... */)

To identify which Flows and their types are available on the page, you can use the ReelFlow.getAvailableFlows() function. This can be useful in cases when you do not wish to hardcode a specific Flow ID, yet target a Flow you know is published on the page.

Swapping two Flows

If you want to swap one Overlay Flow with another, for example when using custom launchers across a page, we recommend this approach:

// Swapping a Flow that is playing (Overlay Flows only)
ReelFlow.getFlow('F-123456ABCD').player.hide()
ReelFlow.getFlow('F-9988776XYZ').player.show()

// Or, if swapping the Eye-catcher  
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.hide()
ReelFlow.getFlow('F-9988776XYZ').eyeCatcher.show()
// Note: This throws an error if either Eye-catcher is disabled

Using any link or page element to launch a Flow

If you wish to start a Flow from a click or other action on a webpage, you don't have to use the API for this, you can achieve this by adding one of our reserved HTML classes or target links, which also makes it easy for non-technical users to enable it via a normal CMS. Learn about using this feature here.

Suppressing the Eye-catcher

The Eye-catcher is the default floating video preview that launches an Overlay player. Suppressing it helps when a page has several Overlay Flows, or when you want to open the Player from your own custom button or "launcher". There are two ways to do it. Both stop the Eye-catcher from rendering, so its preview video isn't loaded unnecessarily.

Option 1: Activation tab, no code

1. Open the Flow in the Dashboard and click Edit.
2. Go to the Activation tab.
3. Turn off the Eye-catcher toggle.

Option 2: ReelFlowSettings, code

Add disabledEyeCatchers to ReelFlowSettings before the Install Code, as shown in Configuring with ReelFlowSettings above.

How the two options combine

If either option disables the Eye-catcher, it stays disabled on the page. ReelFlowSettings can't re-enable an Eye-catcher that's turned off in the Activation tab, and the Activation tab can't override ReelFlowSettings.

To show it, the Eye-catcher must be on in the Activation tab and not listed in ReelFlowSettings.

Calling the API when the Eye-catcher is disabled

If either option disables the Eye-catcher, these eyeCatcher calls throw an error:

ReelFlow.getFlow('F-123456ABCD').eyeCatcher.show();
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.hide();
// Error: "Eye-catcher disabled, enable before making this call"

The player methods still work, so you can open the player from your own button or link:

window.addEventListener('reelflow:ready', () => {
  const button = document.querySelector('#watch-video');
  button.addEventListener('click', () => {
    ReelFlow.getFlow('F-123456ABCD').player.show();
  });
});

Comparing the options

 

Global Methods

getFlow()

To retrieve and interact with a specific Flow.

// Returns a Flow object 
var targetFlow = ReelFlow.getFlow('F-123456ABCD');

// If an invalid ID is specified, it returns `undefined`

getAvailableFlows()

Returns each Flow’s code and type. Pass the code to getFlow() to control it.

var pageFlows = ReelFlow.getAvailableFlows();

var overlay = pageFlows.find(function (f) { return f.type === 'overlay'; });

if (overlay) {
  console.log(overlay.code); // e.g. F-6925bde53d273
  ReelFlow.getFlow(overlay.code).player.show();
}

removeAll()

Completely removes all Flows on a page, including their Eye-catcher and player components.

Note: after removeAll(), getAvailableFlows() still lists the removed Flows and getFlow() still returns them, but calling any of their methods throws "DOM element not found". Don't rely on either to check what's still on the page.

// Removes all Flows on the page from DOM
ReelFlow.removeAll();

getWorkspaceId()

To retrieve the ID of the Workspace the Flows belong to.

// Returns Workspace ID 
var workspaceId = ReelFlow.getWorkspaceId();
// returns 'W-12345678';

Flow object

getFlow() returns a Flow object with two properties: eyeCatcher (Overlay Flows only) and player. Individual Flows can't be removed; use removeAll() to remove every Flow on the page.

Components

Eye-catcher (ReelFlow.getFlow(id).eyeCatcher)

Controls the floating video preview component that exists for Overlay Flows. The Eye-catcher property doesn’t exist for the inline player type.

// Prints "undefined" for inline-type player
console.log(ReelFlow.getFlow("F-123456ABCD").eyeCatcher); 

Methods:

show()

Shows the Eye-catcher if hidden. Throws an error if the Eye-catcher is disabled via the Activation tab or ReelFlowSettings.

Note: This only affects visibility; the component remains in the DOM even when hidden.

ReelFlow.getFlow("F-123456ABCD").eyeCatcher.show();

hide()

Hides the Eye-catcher if visible. Throws an error if the Eye-catcher is disabled via the Activation tab or ReelFlowSettings.

Note: This only affects visibility; the component remains in the DOM even when hidden.

ReelFlow.getFlow("F-123456ABCD").eyeCatcher.hide();

disable()  - Deprecated, use ReelFlowSettings instead (from October 2026)

Still works, but logs a console warning and will be removed in a future version. It hides the Eye-catcher after it has rendered, so it doesn't reduce page load. 

If the Eye-catcher is already disabled via the Activation tab or ReelFlowSettings, calling disable does nothing. Use ReelFlowSettings instead.

// To disable 
ReelFlow.getFlow("F-123456ABCD").eyeCatcher.disable();

// To re-enable, call show()
// ReelFlow.getFlow("F-123456ABCD").eyeCatcher.show();

setMessage()

Replaces the text on the Eye-catcher with your own message. You could use this to greet a visitor by name, or mention their referring page e.g.  "Thanks for visiting from our blog!". The change applies to the current page only: it isn't saved to the Flow, and the Flow doesn't need republishing. 

Accepted values:

• A string – shown as plain text. Spaces at the start and end are removed. HTML isn't rendered, so <b>Hi</b> shows as written. Keep messages to 44 characters or fewer. Longer messages still show, but may not fit the Eye-catcher, and a console warning is logged.

• null, an empty string, or no value – removes your message and shows the Eye-catcher message set in the Flow Builder again.

Any other value, such as a number or an object, throws an error: `"Invalid message, expected a string or null"`. The current message stays as it was.

window.addEventListener('reelflow:ready', () => {
  var eyeCatcher = ReelFlow.getFlow('F-123456ABCD').eyeCatcher;

  // Show a custom message
  eyeCatcher.setMessage('Hi Tom, welcome back!');

  // Go back to the message configured in the Flow Builder
  // eyeCatcher.setMessage(null);
});

Notes:

• Captions: if the Eye-catcher is set to play video captions, your message replaces the captions until you call setMessage(null). A console warning reminds you of this.

• Disabled Eye-catcher: like show() and hide(), this throws "Eye-catcher disabled, enable before making this call" if the Eye-catcher is turned off in the Activation tab or in ReelFlowSettings.

• Page changes: the message is cleared when ReelFlow loads the Flows for a new page, for example on single-page sites. Set it inside your reelflow:ready listener so it's applied each time.

Player (ReelFlow.getFlow(id).player)

Controls the main video player component. On Overlay Flows, player has show(), hide() and on(). Inline players are always visible, so on Inline Flows player only has on(), and calling show() or hide() throws a TypeError.

Methods:

show()

Shows the player if hidden. Takes no arguments. Overlay Flows only, so you can launch the player from your own button or link. See Suppressing the Eye-catcher above for an example.

// Show the player
ReelFlow.getFlow("F-123456ABCD").player.show();

hide()

Hides the player if visible. Overlay Flows only.

ReelFlow.getFlow("F-123456ABCD").player.hide();

Events:

actionButton

Triggered when an action button is clicked. 

var targetFlow = ReelFlow.getFlow("F-123456ABCD");

var removeEventListener = targetFlow.player.on('actionButton:click', (action) => {
    console.log('Action clicked:', action);
    // action = {
    //   id: '9d0d9b93-7cff-4e2e-9acb-bc05181f63e8',
    //   label: 'Chat with us',
    //   index: 0
    // }
});