Advanced option

Control the agent programmatically after the embed loads. Use window.DID_AGENTS_API for functions, events, and runtime configuration.

Prerequisites: Familiarity with the Overview is recommended.

Programmatic API

Once the embed loads, use the global window.DID_AGENTS_API object:

Functions

Function	Description
`speak()`	Make the agent speak text or play audio
`toggleMicState()`	Mute/unmute microphone
`toggleSpeakerState()`	Mute/unmute speaker
`interrupt()`	Stop the agent from speaking
`requestFullscreen()`	Toggle fullscreen mode

Basic usage

const api = window.DID_AGENTS_API;

// Make the agent speak text
await api.functions.speak({
  type: "text",
  input: "Hello! How can I help you?",
});

// Make the agent speak from audio URL
await api.functions.speak({
  type: "audio",
  input: "https://example.com/audio.mp3",
});

// Toggle microphone
api.functions.toggleMicState();      // Toggle current state
api.functions.toggleMicState(true);  // Mute
api.functions.toggleMicState(false); // Unmute

// Toggle speaker
api.functions.toggleSpeakerState();      // Toggle
api.functions.toggleSpeakerState(true); // Mute
api.functions.toggleSpeakerState(false);// Unmute

// Interrupt the agent (stop speaking)
api.functions.interrupt("click"); // Options: 'click', 'audio', 'text'

// Fullscreen
api.functions.requestFullscreen();       // Toggle
api.functions.requestFullscreen(true);  // Enter
api.functions.requestFullscreen(false); // Exit

Event subscription

Subscribe to agent state changes in real time:

Event	Payload	Description
`connection`	`{ state }`	Connection state changes
`agentActivity`	`{ state }`	Agent status: IDLE, TALKING, LOADING, BUFFERING
`chatMode`	`{ state }`	Chat mode: functional, textOnly, maintenance
`error`	`{ error }`	Errors and exceptions

Connection states

connection event states: new, connecting, connected, disconnected, disconnecting, closed, fail, completed

const api = window.DID_AGENTS_API;

const unsubscribe = api.events.on("connection", ({ state }) => {
  console.log("Connection state:", state);

  switch (state) {
    case "new":
      console.log("Connection initialized");
      break;
    case "connecting":
      console.log("Connecting...");
      break;
    case "connected":
      console.log("Connected!");
      break;
    case "disconnected":
      console.log("Disconnected");
      break;
    case "closed":
      console.log("Connection closed");
      break;
    case "fail":
      console.log("Connection failed");
      break;
  }
});

// Clean up when done
unsubscribe();

Agent activity and errors

// Agent activity (IDLE, TALKING, LOADING, BUFFERING)
api.events.on("agentActivity", ({ state }) => {
  console.log("Agent:", state);
});

// Chat mode (functional, textOnly, maintenance)
api.events.on("chatMode", ({ state }) => {
  console.log("Chat mode:", state);
});

// Errors
api.events.on("error", ({ error }) => {
  console.error("Agent error:", error);
});

Complete event example

const api = window.DID_AGENTS_API;
const unsubscribers = [];

unsubscribers.push(
  api.events.on("connection", ({ state }) => updateConnectionIndicator(state))
);
unsubscribers.push(
  api.events.on("agentActivity", ({ state }) => {
    if (state === "TALKING") showSpeakingIndicator();
    else hideSpeakingIndicator();
  })
);
unsubscribers.push(
  api.events.on("error", ({ error }) => {
    logToAnalytics(error);
    showUserError();
  })
);

window.addEventListener("beforeunload", () => {
  unsubscribers.forEach((fn) => fn());
});

Runtime configuration

Use configure() to change settings without reloading:

const api = window.DID_AGENTS_API;

// Position and orientation
api.configure({ position: "left" });        // 'left' or 'right'
api.configure({ orientation: "horizontal" }); // 'horizontal' or 'vertical'

// Display state
api.configure({ openMode: "expanded" });     // 'compact' or 'expanded'

// UI controls
api.configure({
  showChatToggle: false,
  showMicToggle: true,
  showRestartButton: false,
});

// Multiple settings
api.configure({
  position: "right",
  orientation: "vertical",
  showChatToggle: true,
});

// Loader (blurred or opaque overlay)
api.showLoader("Processing...", "blurred");
api.showLoader("Loading...", "opaque");
api.hideLoader();

Common use cases:

Responsive layout changes
Hiding controls by user role
Switching compact/expanded mode
Repositioning based on page layout

Advanced data attributes

Attribute	Type	Default	Description
`data-open-mode`	string	`compact`	Initial state: `compact` or `expanded`
`data-show-restart-button`	string	`true`	Show restart button: `true` or `false`
`data-speech-silence-timeout-ms`	string	-	Timeout (ms) for speech silence detection
`data-external-id`	string	-	Custom user/session identifier
`data-track`	string	`true`	Enable analytics: `true` or `false`
`data-target-id`	string	-	Target element ID for `full` mode

Complete example

<!DOCTYPE html>
<html>
<head>
  <title>Custom Agent Controls</title>
  <style>
    .controls { position: fixed; top: 20px; left: 20px; padding: 20px; background: white; border-radius: 8px; }
    .controls button { display: block; margin: 10px 0; padding: 10px 20px; cursor: pointer; }
  </style>
</head>
<body>
  <div class="controls">
    <h3>Agent Controls</h3>
    <button onclick="makeAgentSpeak()">Make Agent Speak</button>
    <button onclick="toggleMic()">Toggle Mic</button>
    <button onclick="toggleSpeaker()">Toggle Speaker</button>
    <button onclick="interruptAgent()">Stop Agent</button>
    <button onclick="goFullscreen()">Fullscreen</button>
    <div><strong>Status:</strong> <span id="status">Initializing...</span></div>
  </div>

  <script
    type="module"
    src="https://agent.d-id.com/v2/index.js"
    data-mode="fabio"
    data-client-key="{client_key}"
    data-agent-id="{agent_id}"
    data-position="right"
    data-auto-connect="true"
    data-monitor="true"
  ></script>

  <script>
    let api;

    window.addEventListener("load", () => {
      api = window.DID_AGENTS_API;
      api.events.on("connection", ({ state }) => {
        document.getElementById("status").textContent = state;
      });
    });

    function makeAgentSpeak() {
      api.functions.speak({ type: "text", input: "Hello from a button!" });
    }
    function toggleMic() { api.functions.toggleMicState(); }
    function toggleSpeaker() { api.functions.toggleSpeakerState(); }
    function interruptAgent() { api.functions.interrupt("click"); }
    function goFullscreen() { api.functions.requestFullscreen(); }
  </script>
</body>
</html>

Best practices

Wait for API to load

function waitForAPI() {
  return new Promise((resolve) => {
    if (window.DID_AGENTS_API) {
      resolve(window.DID_AGENTS_API);
      return;
    }
    const interval = setInterval(() => {
      if (window.DID_AGENTS_API) {
        clearInterval(interval);
        resolve(window.DID_AGENTS_API);
      }
    }, 100);
  });
}

waitForAPI().then((api) => {
  api.functions.speak({ type: "text", input: "Hello!" });
});

Defer connection until user intent

<script
  type="module"
  src="https://agent.d-id.com/v2/index.js"
  data-mode="fabio"
  data-client-key="{client_key}"
  data-agent-id="{agent_id}"
  data-auto-connect="false"
></script>

<script>
  document.querySelector(".contact-btn").addEventListener("click", () => {
    window.DID_AGENTS_API.configure({ autoConnect: true });
  });
</script>

Clean up event listeners

const cleanup = [];
cleanup.push(api.events.on("connection", handleConnection));
cleanup.push(api.events.on("agentActivity", handleActivity));

window.addEventListener("beforeunload", () => cleanup.forEach((fn) => fn()));

Analytics

With data-monitor="true" and data-track="true", you can track:

Conversation count and duration
User engagement
Common topics
Agent performance
Custom identifiers via data-external-id

View analytics in the D-ID Studio dashboard.

FAQ

The API is available after the embed script loads. Use window.addEventListener("load", ...) or a polling function to avoid calling it before it's ready.

Use different data-name values for each script. Each embed exposes its own API; you may need to scope your code to the correct agent instance.

The embed provides a prebuilt UI. For full customization, use the D-ID Agents SDK to build your own interface.

Use click, audio, or text to indicate the source of the interrupt. This helps with analytics and debugging.

Next steps

Overview — Basic configuration
D-ID Agents SDK — Custom UI
Agents Streams V2 — Backend integration
Create agents — Create agents via API

Support

Have any questions? We're here to help! Go to the Help Center or send us a message.

Contact Support