JavaScript API

Overview

In some advanced embedding cases, such as single-page apps (SPAs), there is a need to control the Videobot dynamically after the page has loaded. For instance, the Videobot should only be shown in certain pages or situations, but the page does not refresh between user actions.

One option for solving these cases is using Videobot's JavaScript-based API.

Methods

The main way to interact with a Videobot on the page is through the global object window.Videobot, which is created after the initial Videobot script has loaded.

Currently the following methods are considered publicly available:

Method	Description
window.Videobot.refresh()	Reload Videobot and its configuration
window.Videobot.remove()	Remove Videobot from the page
window.Videobot.open()	Open Videobot iframe
window.Videobot.close()	Close Videobot iframe
window.Videobot.show()	Show Videobot widget & iframe (if previously hidden)
window.Videobot.hide()	Hide Videobot widget & iframe (and pause video)
window.Videobot.enableAnalytics()	Enable analytics events
window.Videobot.disableAnalytics()	Disable analytics events
window.Videobot.setGoogleConsent(value)	Define user consent for Google Analytics

WARNING

These methods will not be available before the Videobot script has loaded, see the Examples section for a possible solution.

Messages

In addition to the callable methods, the Videobot itself communicates with the widget and the parent page with message events. To learn more about how they work, see this guide on MDN.

Messages from the Videobot are objects with an action and optional per-action value fields:

{
	action: 'VIDEO_BOT_LOADED',
	...
}

The actions that can be used are:

Message	Description
VIDEO_BOT_LOADED	The Videobot has initialized and will be shown
VIDEO_BOT_OPEN	The Videobot has been opened
VIDEO_BOT_CLOSE	The Videobot has been closed
VIDEO_BOT_ANALYTICS_EVENT	An analytics event from within the Videobot. Requires the Iframe forwarding feature to be enabled

INFO

Always check the origin of the incoming event to ensure it comes from Videobot

Examples

If we wanted to only show the Videobot on the /campaign page of our site, we could do the following:

if (window.location.pathname === '/campaign') {
	window.Videobot.show()
} else {
	window.Videobot.hide()
}

As another example, we could dynamically allow enabling analytics based on a custom consent button:

<button onclick="window.Videobot.enableAnalytics()">Allow analytics</button>

If we wanted to use the above examples immediately after the page has loaded, we should wait for the DOMContentLoaded event to fire:

document.addEventListener('DOMContentLoaded', (event) => {
	window.Videobot.hide()
})

Alternatively the Videobot script can be imported as a module:

<script type="module">
  import { Videobot } from 'https://videobot.com/embed/videobot.mjs'
  Videobot.hide()
</script>

Placement API

Methods

When a Videobot placement is configured, you can interact with it through the global object window.VideobotPlacement, which becomes available after the placement script has loaded.

Currently the following methods are considered publicly available:

Method	Description
VideobotPlacement.configure(options)	Initialize the placement system
VideobotPlacement.setParam(key, value, options?)	Set a single parameter
VideobotPlacement.setParams(params, options?)	Set multiple parameters at once
VideobotPlacement.removeParam(key)	Remove a parameter
VideobotPlacement.getParams()	Returns a copy of the current parameters
VideobotPlacement.refresh()	Immediately re-resolve all placements, bypassing debounce
VideobotPlacement.onResolve(callback)	Register a listener for placement resolve events. Returns an unsubscribe function

configure()

Initializes the placement system. Call this once when your page loads.

VideobotPlacement.configure({
  accountId: "your_account_id",
  placements: { hero: "placement_key_123" },
  params: { country: "DE" },
  debounce: 500
})

Option	Description
accountId	Your Videobot account public ID
placements	A map of placement names to their keys
params	Initial parameters to send with the first request
debounce	Debounce delay in milliseconds before refreshing after param changes (default: 300)

Parameters set before configure() (via setParam or setParams) are queued and merged with the params option at configuration time.

TIP

Use { silent: true } with setParams to batch multiple updates without triggering a refresh for each one. Only the last call without silent triggers the refresh.

Lifecycle

Before configure()

Any setParam or setParams calls made before configure() are stored in a pending queue. They are automatically merged when configure() is called.

// Page loads, params set early
VideobotPlacement.setParams({ country: "DE" })

VideobotPlacement.configure({
  accountId: "abc",
  placements: { hero: "key123" }
})
// First API call includes: { country: "DE" }

Runtime updates

When parameters change after configuration, the placement system:

1. Waits for the debounce period (300ms by default) to collect rapid changes
2. Sends a single API request with the updated parameters
3. If the response returns different content, replaces the current widget

Examples

The following examples show common use cases for the Placement API.

Set parameters

VideobotPlacement.setParams({
  user_type: "enterprise",
  country: "FI"
})

Remove parameters

VideobotPlacement.removeParam("user_type")
VideobotPlacement.removeParam("country")

Listen for resolved content

const unsubscribe = VideobotPlacement.onResolve(({ placementName, content }) => {
  // process resolved content
})

unsubscribe()