Control & Methods

Control the embedded agent programmatically using the global window.DID_AGENTS_API object. Call functions to control agent behavior and update configuration at runtime.

When to Use

Use runtime methods and configuration when:

You need dynamic changes based on user actions (theme changes, preferences)
You want responsive layout adjustments (screen size, orientation)
You're A/B testing different configurations
You need conditional UI based on user roles or context

For static initial configuration, use HTML data attributes on the script tag instead.

Available Functions

The API exposes functions for controlling agent behavior, audio, and display.

Function	Description	Parameters
`speak()`	Make the agent speak text or play audio	`{ type, input }`
`toggleMicState()`	Mute/unmute the user's microphone	`boolean` (optional)
`toggleSpeakerState()`	Mute/unmute the agent's audio output	`boolean` (optional)
`interrupt()`	Stop the agent from speaking immediately	None
`requestFullscreen()`	Enter or exit fullscreen mode	`boolean` (optional)

speak()

Make the agent speak custom text or play audio from a URL.

Parameters

Parameter	Type	Description	Required
`type`	string	Speech type: `text` or `audio`	Yes
`input`	string	Text to speak or audio URL	Yes

Examples

const api = window.DID_AGENTS_API;

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

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

Use cases:

Proactive greetings when user lands on page
Announcements or notifications
Custom responses to user actions
Playing pre-recorded audio content

toggleMicState()

Control the user's microphone state.

Parameters

Parameter	Type	Description	Required
`state`	boolean	`true` to mute, `false` to unmute, or omit to toggle	No

Examples

// Toggle current state
api.functions.toggleMicState();

// Explicitly mute
api.functions.toggleMicState(true);

// Explicitly unmute
api.functions.toggleMicState(false);

Use cases:

Custom mute buttons in your UI
Auto-mute when switching tabs
Privacy controls
Meeting-style controls

toggleSpeakerState()

Control the agent's audio output.

Parameters

Parameter	Type	Description	Required
`state`	boolean	`true` to mute, `false` to unmute, or omit to toggle	No

Examples

// Toggle current state
api.functions.toggleSpeakerState();

// Explicitly mute agent
api.functions.toggleSpeakerState(true);

// Explicitly unmute agent
api.functions.toggleSpeakerState(false);

Use cases:

Custom speaker controls
Quiet mode for public spaces
Accessibility features
User preference settings

interrupt()

Immediately stop the agent from speaking. Useful when the agent is talking but the user wants to interrupt or skip ahead.

Examples

// Stop the agent immediately
api.functions.interrupt();

Use cases:

Skip button in custom UI
User interruption handling
Emergency stop controls

requestFullscreen()

Enter or exit fullscreen mode for the agent interface.

Parameters

Parameter	Type	Description	Required
`state`	boolean	`true` to enter, `false` to exit, or omit to toggle	No

Examples

// Toggle fullscreen
api.functions.requestFullscreen();

// Enter fullscreen
api.functions.requestFullscreen(true);

// Exit fullscreen
api.functions.requestFullscreen(false);

Use cases:

Immersive mode for presentations
Focus mode for conversations
Mobile-optimized experience
Custom fullscreen buttons

Runtime Configuration

Use configure() to change settings dynamically without reloading the page.

Configuration Options

Option	Type	Default	Description
`position`	string	`right`	Position: `left` or `right`
`orientation`	string	`vertical`	Orientation: `horizontal` or `vertical`
`openMode`	string	`compact`	Display state: `compact` or `expanded`
`showChatToggle`	boolean	`true`	Show/hide chat toggle button
`showMicToggle`	boolean	`true`	Show/hide microphone toggle button
`showRestartButton`	boolean	`true`	Show/hide restart conversation button
`autoConnect`	boolean	`false`	Auto-connect on load

Examples

Change Position and Orientation

// Move to left side
api.configure({ position: "left" });

// Change to horizontal orientation
api.configure({ orientation: "horizontal" });

// Both at once
api.configure({
  position: "left",
  orientation: "horizontal",
});

Control UI Elements

// Hide chat toggle
api.configure({ showChatToggle: false });

// Hide all optional buttons
api.configure({
  showChatToggle: false,
  showMicToggle: false,
  showRestartButton: false,
});

Change Display State

// Start expanded
api.configure({ openMode: "expanded" });

// Switch to compact
api.configure({ openMode: "compact" });

Initialization Patterns

Wait for API to Load

Always check that window.DID_AGENTS_API exists before calling methods.

Pattern 1: Polling with Promise

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); // Check every 100ms
  });
}

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

Pattern 2: Window Load Event

window.addEventListener("load", () => {
  const api = window.DID_AGENTS_API;

  // API is available, safe to use
  api.events.on("connection", ({ state }) => {
    console.log("Connection:", state);
  });
});

Pattern 3: Direct Check

function initAgent() {
  if (!window.DID_AGENTS_API) {
    console.warn("Agent API not loaded yet");
    return;
  }

  const api = window.DID_AGENTS_API;
  // Use API...
}

// Try after short delay
setTimeout(initAgent, 1000);

Responsive Design

Adapt the agent orientation and position based on screen size.

window.addEventListener("load", () => {
  const api = window.DID_AGENTS_API;

  function updateLayout() {
    const isMobile = window.innerWidth < 768;
    const isTablet = window.innerWidth >= 768 && window.innerWidth < 1024;

    if (isMobile) {
      api.configure({
        position: "right",
        orientation: "vertical",
        openMode: "compact",
      });
    } else if (isTablet) {
      api.configure({
        position: "right",
        orientation: "vertical",
        openMode: "expanded",
      });
    } else {
      api.configure({
        position: "left",
        orientation: "horizontal",
        openMode: "expanded",
      });
    }
  }

  updateLayout();
  window.addEventListener("resize", updateLayout);
});

Advanced Patterns

Proactive Greeting

Greet users when they land on specific pages.

window.addEventListener("load", () => {
  const api = window.DID_AGENTS_API;

  api.events.on("connection", ({ state }) => {
    if (state === "connected") {
      api.functions.speak({
        type: "text",
        input: "Hi! I'm here to help. What can I do for you?",
      });
    }
  });
});

A/B Testing

Test different configurations.

const variant = getABTestVariant(); // Your A/B testing logic

const config =
  variant === "A"
    ? { position: "right", openMode: "compact" }
    : { position: "left", openMode: "expanded" };

window.addEventListener("load", () => {
  const api = window.DID_AGENTS_API;
  api.configure(config);
});

FAQ

The API is available after the embed script loads. Use one of the initialization patterns above: window load event, polling with Promise, or direct check.

Yes. Most methods return promises, so you can chain them or use async/await:

await api.functions.speak({ type: "text", input: "Starting demo..." });
await api.functions.requestFullscreen(true);

It depends. Use data-auto-connect="true" for dedicated agent pages where connection is expected. Use false (default) for marketing pages where the agent is optional. This saves bandwidth and resources.