Live Video-Only Embedding

This section guides you on how to use embed just the live video component of the Digital Human experience. You'll learn to send events from your page directly into the video-only iframe, concealing all other frontend elements.

The video only mode allows customers running UNITH’s digital heads in an iframe to have a bi-directional communication with their digital humans. This means customers can now send events to the digital humans from their web applications and also listen for events from said heads.

This is made possible by our secure implementation of the window.postMessage() method which safely allows cross-origin communication between a page and an iframe embedded in it.

info

To see it in action, check out this example here: Link.

info

Live video-only mode using iframe is only available for legacy digital humans. If your digital human uses streaming mode, please refer to our SDK documentation instead.

To check whether your digital human is in legacy or streaming mode, see this page.

If the digital human configuration states that videoStreaming=true then your digital human is in streaming mode.

Prerequisites

error_outline

You must have the ADMIN role to access the following endpoints.

There are two necessary prerequisites to running video-only mode:

Add the URL where the iframe will run inside the Allowed Iframe Origins section in your Unith Interface "security" tab.

code

<iframe
  id="my-iframe"
  src="https://chat.unith.ai/ORG-1/HEAD-1?api_key=KEY&mode=video"
  width="75%"
  height="100%"
  allow="microphone">
</iframe>

How it works:

Communication between your app and the iframe is done by passing our custom event names to the "postMessage" method.

The table below outlines the events we support and respective parameters:

Event Name	Event Payload	Description
`DH_READY`	:::BlockQuote
{ isReady: boolean }
:::	Originator : UNITH’s Iframe This event is sent to your app when the Digital Human has fully loaded and is ready to process messages.
`DH_MESSAGE`	:::BlockQuote
{ message:string }
:::	Originator: Your App Send this event and payload to prompt the Digital Human (DH) to process your input.
`DH_PROCESSING`	:::BlockQuote
{ processing: boolean }
:::	Originator: UNITH’s Iframe This event is sent to your app when the digital head is processing a your input.

Examples:

Registering your event listeners:

code

window.addEventListener("message", function (event) {
      // only allow events from unith's iframe
      if (event.origin !== "https://chat.unith.ai") return;
      const payload = event.data.payload;
      const name = event.data.event;
      switch (name) {
        case "DH_READY":
          if (payload && payload.isReady) {
            // Digital human is ready
          }
          break;
        case "DH_PROCESSING":
          if (payload && payload.processing){
            // Digital human is processing input
          }
          break;
        default:
          break;
      }
    });

Sending a message to the digital human:

code

iframe.contentWindow.postMessage(
  {
      event: "DH_MESSAGE",
      payload: {
        message: 'test message'
      }
    },
    "https://chat.unith.ai" // only send events to unith's iframe
  );

For a fully functioning example, please check out any of our sample applications on github:

scheduleLast updated Feb 25, 2026