UNITH Embed Integration Guide

overview the unith embed system provides the simplest and fastest way to integrate digital humans into your website or application we offer a custom web component ( \<unith widget> ) that can be embedded on any website using standard html, or integrated into modern frameworks like react and next js this guide covers three integration methods standard html integration using the custom \<unith widget> element react/next js integration framework specific implementation iframe integration alternative embedding approach all integration methods require three core credentials public head id, public org id, and public api key these can be found in your unith url for a specific head or inside the interface > edit section your public org id and public api key will remain the same across all heads \<font color="#45709d">\</font> digital human unith url ⚠️ important api key ≠ secret key the api key is public and can be included in visible urls the secret key is private and must never be exposed they are completely different credentials internal ids (uuids) and public ids (slugs) can refer to the same resource, but they are not interchangeable using the wrong type will result in authentication or resolution errors standard html integration step 1 add the embedding script include the unith embed script in your html the defer attribute ensures the script loads after the page content \<script src="https //embedded stream unith ai/index js" defer>\</script> step 2 add the widget element choose between fullscreen mode or widget mode based on your integration needs fullscreen mode (default) for fullscreen integration, wrap the \<unith widget> element in a container with defined dimensions \<div style="height 400px; width 100%;"> \<unith widget head id="yourpublicheadid" org id="yourpublicorgid" api key="yourpublicapikey" \> \</unith widget> \</div> in fullscreen mode (default), you must wrap \<unith widget> in a container div with a defined height without this, the digital human interface may not display correctly widget mode (floating button) for a floating widget that appears as a chat button on your page configuration attributes core attributes (required) these three attributes are required for all unith embed integrations attribute description type example public head id unique identifier for your digital human string "lola 1234" public org id organization identifier from your unith profile string "unith 123" public api key api key associated with your account string "uk abc123xyz " you can use the public org id and public head id and public api key directly from the url of your digital human www chat unith ai/ orgid 123/headid 123?api key=1234 secondary attributes (optional) display & localization language sets the ui display language for interface elements (buttons, labels, system messages) type string (language code) default user's browser or device language example language="en us" supported languages language code language ar ae arabic (united arab emirates) bg bg bulgarian (bulgaria) bn bd bengali (bangladesh) bs ba bosnian (bosnia and herzegovina) cs cz czech (czechia) de de german (germany) en us english (united states) es es spanish (spain) fi fi finnish (finland) fr fr french (france) hu hu hungarian (hungary) id id indonesian (indonesia) it it italian (italy) ka ge georgian (georgia) kk kz kazakh (kazakhstan) lt lt lithuanian (lithuania) lv lv latvian (latvia) nl nl dutch (netherlands) pl pl polish (poland) pt pt portuguese (portugal) ro ro romanian (romania) ru ru russian (russia) sv se swedish (sweden) sk sk slovak (slovakia) sl si slovenian (slovenia) sr rs serbian (cyrillic, serbia) th th thai (thailand) tr tr turkish (turkey) uk ua ukrainian (ukraine) example ui variant & placement variant controls the ui display mode type string default "fullscreen" supported values "fullscreen", "compact", "widget" example variant="widget" placement controls widget position when variant="widget" only applies to widget mode type string default "bottom right" supported values value description "top left" top left corner "top" top center "top right" top right corner "bottom left" bottom left corner "bottom" bottom center "bottom right" bottom right corner example widget with custom placement auto open automatically opens the widget when a visitor accesses your web page, without requiring a click to expand it type boolean default false applies to variant= "widget" only example auto open="true" auto open delay sets the delay before the widget auto opens, in milliseconds only applicable when auto open="true" type number default 0 example auto open delay="3000" (3 seconds = default value) url query parameter example https //stream unith ai/{public org id}/{public head id}?api key={public api key}\&variant=widget\&auto open=true\&auto open delay=5000 user identification & session tagging you can pass a username and a tag when embedding a streaming digital human both values appear as dedicated columns in your conversation logs retrieval docid\ ozjbzgbny7087mkwemutz , making it straightforward to filter and segment sessions without parsing session ids you can supply these values either as widget attributes or as url query parameters username type string example username="alice johnson" tag type string example tag="campaign summer2025" example https //stream unith ai/publicorgid/publichead id= \&username=alice\&tag=campaign summer2025 for full details on filtering logs by username and tag, see conversation logs retrieval docid\ ozjbzgbny7087mkwemutz speech to text configuration stt provider selects the speech recognition provider for voice input type string default "azure" supported values "azure", "eleven labs" example stt provider="eleven labs" example elevenlabs stt advanced configuration the following attributes are only applicable when stt provider="eleven labs" noise suppression enables background noise filtering for clearer voice recognition type boolean default true example noise suppression="true" vad silence threshold secs duration of silence (in seconds) required to detect end of speech type number default 1 5 range 0 5 3 0 example vad silence threshold secs="1 5" vad threshold voice activity detection sensitivity threshold lower values are more sensitive to speech type number default 0 4 range 0 0 1 0 example vad threshold="0 4" min speech duration ms minimum duration (in milliseconds) of audio to be considered speech type number default 100 example min speech duration ms="100" min silence duration ms minimum duration (in milliseconds) of silence between speech segments type number default 100 example min silence duration ms="100" disable dynamic speech recognition take advantage of the elevenlab's automatic language detection when set to true the speech recognition will only focus on the voice set by languagespeechrecognition parameter learn more about digital human creation here https //docs unith ai/create a digital human type boolean default false example disable dynamic speech recognition=true complete elevenlabs stt example url query parameter example https //stream unith ai/{org id}/{head id}?api key={api key}\&stt provider=eleven labs\&vad silence threshold secs=1\&vad threshold=0 4\&min speech duration ms=100\&min silence duration ms=100 voice interruptions enables users to interrupt the digital human during response delivery for more natural, conversational interactions type boolean default false supported stt providers azure, elevenlabs example voice interruptions="true" how it works when voice interruptions are enabled, users can speak while the digital human is responding upon detecting an interruption, the system automatically crossfades back to the idle state and begins listening to the new user input the interrupted response is terminated, and the conversation continues with the user's new message url query parameter example https //stream unith ai/{public org id}/{public head id}?api key={public api key}\&voice interruptions=true voice interruptions create a more natural conversational flow, allowing users to clarify, correct, or redirect the conversation without waiting for the complete response however, incomplete inputs may occur if users interrupt mid thought subs enabled enables display of subtitles showing the digital human's spoken responses as text type boolean default false example subs enabled="true" url query parameter example https //stream unith ai/{public org id}/{public head id}?api key={public api key}\&subs enabled=true synchronization note due to the streaming nature of audio generation and varying speech synthesis speeds, there may be slight timing differences between audio playback and subtitle display react / next js integration for react and next js applications, follow these steps to properly integrate the unith widget step 1 load the embed script use react's useeffect hook to dynamically load the unith embed script when your component mounts import { useeffect } from 'react'; useeffect(() => { // load the script const script = document createelement('script'); script src = 'https //embedded stream unith ai/index js'; script defer = true; document body appendchild(script); return () => { // cleanup remove script when component unmounts document body removechild(script); }; }, \[]); step 2 add the widget element fullscreen mode \<div style={{ height '400px', width '100%' }}> \<unith widget head id="yourpublicheadid" org id="yourpublicorgid" api key="yourpublicapikey" \> \</unith widget> \</div> widget mode \<unith widget head id="yourpublicheadid" org id="yourpublicorgid" api key="yourpublicapikey" variant="widget" placement="bottom right" \> \</unith widget> step 3 typescript configuration (typescript projects only) if you're using typescript, add type definitions to prevent typescript errors create or update global d ts declare namespace jsx { interface intrinsicelements { \['unith widget'] { head id string; org id string; api key string; variant? 'widget' | 'fullscreen' | 'compact'; placement? 'bottom right' | 'bottom left' | 'top right' | 'top left' | 'top' | 'bottom'; language? string; username? string; stt provider? 'azure' | 'eleven labs'; noise suppression? boolean; vad silence threshold secs? number; vad threshold? number; min speech duration ms? number; min silence duration ms? number; }; } } update tsconfig json add the global d ts file to your typescript configuration { "include" \["global d ts", "src/ / "] } complete react component example import { useeffect } from 'react'; export default function digitalhumanembed() { useeffect(() => { const script = document createelement('script'); script src = 'https //embedded stream unith ai/index js'; script defer = true; document body appendchild(script); return () => { document body removechild(script); }; }, \[]); return ( \<div style={{ height '500px', width '100%' }}> \<unith widget head id="yourpublicheadid" org id="yourpublicorgid" api key="yourpublicapikey" language="en us" username="current user" \> \</unith widget> \</div> ); } iframe integration as an alternative to the custom web component, you can embed the digital human using a standard html iframe basic iframe implementation the allow="microphone" attribute is required to enable voice input functionality in the iframe customization with query parameters pass secondary attributes as url query parameters to customize the iframe embed example with multiple parameters query parameter format parameter example value required api key yourapikey yes language en us no stt provider eleven labs no username alice no noise suppression true no vad silence threshold secs 1 0 no vad threshold 0 4 no min speech duration ms 100 no min silence duration ms 100 no voice interruptions true no subs enabled true no placement center no integration examples by use case customer support widget a floating widget in the bottom right corner with user tracking fullscreen product demo an embedded fullscreen experience for product demonstrations multilingual educational platform a compact widget with optimized voice recognition for education important notes browser compatibility currently, we only support google chrome browser microphone permissions users will be prompted to grant microphone access when they first interact with the digital human ensure your website uses https, as modern browsers require secure contexts for microphone access script loading the embed script ( index js ) should be loaded with the defer attribute to ensure it executes after the dom is fully parsed container dimensions in fullscreen and compact modes, always define explicit height and width for the container div the widget will inherit these dimensions typescript support for typescript projects, always add the global d ts type definitions to prevent compilation errors with the custom \<unith widget> element query parameter encoding when using iframe integration with query parameters, ensure special characters in api keys are properly url encoded username tracking the username attribute is automatically included in session ids and conversation logs, enabling user specific analytics and tracking elevenlabs stt parameters advanced voice activity detection (vad) parameters are only applicable when using stt provider="eleven labs" these settings will be ignored for azure stt troubleshooting widget not displaying issue the \<unith widget> element appears but doesn't render the digital human interface solution ensure the parent container has defined height and width dimensions in fullscreen mode, the widget requires explicit dimensions to render correctly microphone access denied issue the digital human cannot access the microphone for voice input solution verify your site uses https (required for microphone access) for iframe integration, ensure allow="microphone" attribute is present check browser permissions and ensure microphone access is granted typescript errors issue typescript reports errors about unknown element \<unith widget> solution add the global d ts type definitions file as described in the react/next js integration section, and ensure it's included in your tsconfig json