Skip to main content

​
Overview

Every AgentHuman link can be embedded directly into your web page as an <iframe>. The embedded page communicates bidirectionally with the parent via the postMessage API, so you can control it and react to call events from your own code.

​
Embedding the Page

Get your link URL from app.agenthuman.com/links and use it as the src: 
<iframe
  id="ah-room"
  src="https://your-link-url"
  allow="microphone; camera; fullscreen"
  style="width: 100%; height: 100%; border: none;"
></iframe>

​
Customization via Query Parameters

All query parameters available for the direct link — language, theme colors and auto-hide behavior — work identically when embedding as an iframe. Append them to the src URL: 
<iframe
  src="https://your-link-url?lang=es&primary_color=3c83f6&auto_hide=false"
  allow="microphone; camera; fullscreen"
  style="width: 100%; height: 100%; border: none;"
></iframe>

​
Controlling the Page (Commands)

Send commands from your parent page into the iframe using postMessage. The easiest way is with the createRoomClient helper.

​
Using createRoomClient

import { createRoomClient } from "@agenthuman/room/roomClient";

const iframe = document.getElementById("ah-room") as HTMLIFrameElement;
const room = createRoomClient(iframe);

room.mute(true);           // Mute the microphone
room.setSpeaker(true);     // Mute the speaker
room.endCall();            // End the call
room.showControls(true);   // Show or hide the control bar
room.setFullscreen(true);  // Enter or exit fullscreen
room.setAutoHide(false);   // Disable the auto-hide inactivity timer

​
Raw postMessage Commands

If you prefer not to use the helper, send messages directly: 
const iframe = document.getElementById("ah-room");

iframe.contentWindow.postMessage(
  {
    source: "agenthuman-room-command",
    type: "room:set_mute",
    payload: { muted: true }
  },
  "*"
);
Available command types:
Command typePayloadDescription
room:set_mute{ muted: boolean }Mute or unmute the microphone
room:set_speaker{ muted: boolean }Mute or unmute the speaker
room:end_call—End the call
room:show_controls{ visible: boolean }Show or hide the control bar
room:set_fullscreen{ enter: boolean }Enter or exit fullscreen
room:set_auto_hide{ enabled: boolean }Enable or disable the auto-hide timer

​
Listening to Events

The page fires postMessage events to the parent window as the call state changes. Listen for them with a message event handler: 
window.addEventListener("message", (event) => {
  const { source, type, payload, timestamp } = event.data;

  if (source !== "agenthuman-room") return;

  switch (type) {
    case "room:connecting":
      console.log("Connecting...");
      break;
    case "room:connected":
      console.log("Connected");
      break;
    case "room:reconnecting":
      console.log("Reconnecting...");
      break;
    case "room:ended":
      console.log(`Call ended after ${payload.duration}s`);
      break;
    case "room:mute_changed":
      console.log("Mic muted:", payload.muted);
      break;
    case "room:speaker_changed":
      console.log("Speaker muted:", payload.muted);
      break;
    case "room:mic_permission":
      console.log("Mic permission:", payload.permission); // "granted" | "denied" | "prompt"
      break;
    case "room:mic_device_changed":
      console.log("Mic device:", payload.deviceId, payload.deviceLabel);
      break;
    case "room:fullscreen_changed":
      console.log("Fullscreen:", payload.isFullscreen);
      break;
  }
});
Event reference:
Event typePayload fieldsDescription
room:connecting—Establishing connection
room:connected—Connected and ready
room:reconnecting—Lost connection, retrying
room:endedduration: numberCall ended; duration is call length in seconds
room:mute_changedmuted: booleanMicrophone mute state changed
room:speaker_changedmuted: booleanSpeaker mute state changed
room:mic_permissionpermission: "granted" | "denied" | "prompt"Browser microphone permission status
room:mic_device_changeddeviceId: string, deviceLabel: stringActive microphone device changed
room:fullscreen_changedisFullscreen: booleanFullscreen state changed
All events include a source: "agenthuman-room" field and a timestamp (Unix ms).