Live Video-Only Embedding

6min

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. 
To see it in action, check out this example here: Link.﻿
Prerequisites
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 dashboard settings (coming soon)
Add your URL using the following endpoint via our API: /head/{id}/allowed-origins and /head/{id}/iframe/allowed-origins﻿
Append the query param "&mode=video" to your iframe source. A correct implementation should look like this:
HTML
<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>
<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
{
  isReady: boolean
}
Originator : UNITH’s Iframe
This event is sent to your app when the digital head has fully loaded and is ready to process messages.
DH_MESSAGE
{
  message:string
}
Originator: Your App
Send this event and payload to prompt the digital head (DH) to process your input.
DH_PROCESSING
{
  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: 
﻿
JS
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;
      switch (event.data.type) {
        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;
      }
    });
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;
      switch (event.data.type) {
        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: 
JS
iframe.contentWindow.postMessage(
  {
      type: "DH_MESSAGE",
      payload: {
        message: 'test message'
      }
    },
    "https://chat.unith.ai" // only send events to unith's iframe
  );
iframe.contentWindow.postMessage(
  {
      type: "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:
﻿Vanilla JS﻿
﻿React JS﻿
﻿
﻿
﻿

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

Updated 18 Dec 2024

Did this page help you?

Customising the Embedded Digital Human

Conversational Plugins