Skip to main content

​
Configure the AvaturnHead

import { AvaturnHead } from "@avaturn-live/web-sdk";

const avatar = new AvaturnHead(domElement, {
  apiHost: "https://api.avaturn.live",
  sessionToken: "<YOUR_SESSION_TOKEN>",
  preloadBundle: false,
  preconnect: false,
  keepAlive: false,
  audioSource: false,
  immediatelyJoin: true,
});

await avatar.init()

​
Properties

​
domElement
HTMLElement
Reference to the DOM element where you want to place the video
​
sessionToken
string
required
Your authorization session token
​
apiHost
string
default:"https://api.avaturn.live"
Parameter for overriding the default api host. In most cases, it should not be used.
​
preloadBundle
boolean
default:"false"
The preloadBundle parameter controls the preloading of the JavaScript bundle required for the SDK to function properly.Why is this important?When preloading is enabled (preloadBundle: true), the SDK automatically loads and caches all necessary resources (JavaScript bundle) before they are actually needed. This reduces the delay during the first interaction with the SDK, improving performance and providing a smoother user experience.When should you use preloading?
  • If your application requires quick, responsive performance when first using the SDK.
  • In cases where you want to minimize delays caused by dynamically loading resources.
When might you not need preloading?
  • If your application is not sensitive to initial delays when the SDK is first used.
  • In scenarios where you want to manage resource loading manually.
​
preconnect
boolean
default:"false"
The preconnect parameter controls the preconnection of the avatar to the stream before the session has been fully initialized.Why is this important?When preconnection is enabled (preconnect: true), the SDK preemptively connects the avatar to the stream even if the session has not been fully initialized yet. This reduces the delay in establishing a connection with the server, which is particularly useful for scenarios where the avatar needs to be ready for interaction with minimal latency.When should you use preconnection?
  • If it’s important for the avatar to be ready for user interaction with minimal delay after the session starts.
  • In situations where you want to speed up the connection to the stream.
When might you not need preconnection?
  • If your application is not sensitive to the delay when connecting the avatar to the stream.
  • If you prefer to manage the connection process manually.
​
keepAlive
boolean
default:"false"
The keepAlive parameter controls whether the connection to the stream will be maintained if there is no interaction with the avatar for five minutes.Why is this important?When the keepAlive flag is set to true, the SDK keeps the stream connection active even if there has been no interaction with the avatar for five minutes. This is useful in scenarios where you need the stream to remain active despite temporary inactivity.If keepAlive is set to false, the SDK will automatically disconnect the stream after five minutes of inactivity, helping to conserve resources.When should you use keepAlive?
  • If you need the stream to remain active regardless of temporary user inactivity.
  • In cases where reconnecting takes time and instant readiness is important.
When might you not need keepAlive?
  • If you want to automatically free up resources when there is no interaction with the avatar.
  • If reconnecting to the stream is not critical for your application.
​
audioSource
boolean
default:"false"
The audioSource parameter controls whether to use the user’s microphone for voice communication with the avatar.Why is this important?When audio source is enabled (audioSource: true), the SDK will request microphone permissions and allow the user to communicate with the avatar using voice input. This enables natural voice-based interaction with the avatar.When disabled (audioSource: false), voice communication is not available, and you will need to implement text-based functionality using the appropriate SDK methods.When should you enable audioSource?
  • If you want to provide voice-based interaction with the avatar for a more natural conversation experience.
  • In scenarios where hands-free communication is preferred or required.
When might you not need audioSource?
  • If you prefer to implement text-based communication only.
  • In environments where microphone access is not available or desired.
  • If you want to manage audio input manually through other SDK methods.
​
immediatelyJoin
boolean
default:"true"
The immediatelyJoin parameter controls whether to automatically connect to the avatar room as soon as the SDK is ready.Why is this important?When immediate joining is enabled (immediatelyJoin: true), the SDK automatically connects to the avatar room once initialization is complete, and the user will immediately see and hear the avatar.When disabled (immediatelyJoin: false), you need to wait for the init() method promise to resolve or listen for the init event, then manually call the join() method to connect to the room. This gives you control over the exact moment when the user connects and starts interacting with the avatar.When should you enable immediatelyJoin?
  • If you want the avatar to be available immediately after SDK initialization.
  • In scenarios where you want a seamless, automatic connection experience.
When might you disable immediatelyJoin?
  • If you need to control the exact timing of when the user connects to the avatar room.
  • When you want to perform additional setup or user interactions before showing the avatar.
  • If you need to implement custom logic between SDK initialization and room connection.