# Metered Embed SDK -- llms.txt reference
(last updated: 2026-05-05)

> Complete API reference for the Metered Embed Frame SDK. Covers initialization, methods, events, and room-level iFrame options for embedding video chat into any website or app.

## Overview

Metered Embed allows you to embed video calls and text chat into any existing app or website in minutes. It is an iframe-based solution that provides video calling, screen-sharing, live streaming, and chat capabilities. You include the Frame SDK script, create a `MeteredFrame` instance, call `init()` with a room URL, and the SDK mounts an iframe into a target DOM element.

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. Your **app name** (e.g. `yourappname`) is shown on the Dashboard home page. It forms your domain: `yourappname.metered.live`.
3. **Create a room**: Go to **Dashboard → Rooms** and click "Create Room", or use the REST API. Each room gets a URL: `yourappname.metered.live/roomname`.
4. For **private rooms**, generate access tokens via the REST API. The **Secret Key** for API calls is found in **Dashboard → Developers**. Never expose it in front-end code.
5. Use the room URL in the Embed SDK's `init()` call to embed video chat.

## Setup

### CDN URL

```html
<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
```

### Minimal embed code

```html
<div id="metered-frame"></div>
<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
<script>
    var frame = new MeteredFrame();
    frame.init({
        roomURL: "yourappname.metered.live/tutorial",
    }, document.getElementById("metered-frame"));
</script>
```

### How it works

1. Include the Frame SDK script tag.
2. Add a `<div>` element to your page where the embed should appear.
3. Create a new `MeteredFrame` instance: `var frame = new MeteredFrame();`
4. Call `frame.init(options, domElement)` to mount the iframe.

## Init Options

The `init()` method accepts an options object as its first argument. These options control the behavior and appearance of the embedded meeting.

| Option | Type | Required | Description | Default |
|---|---|---|---|---|
| `roomURL` | string | YES | URL of the Meeting Room (e.g. `yourappname.metered.live/roomname`). | -- |
| `width` | string | NO | Width of the embed (CSS value, e.g. `"100px"`, `"50%"`). | `"100%"` |
| `height` | string | NO | Height of the embed (CSS value). | `"600px"` |
| `autoJoin` | boolean | NO | When `true`, users skip the Lobby/Join Meeting page and enter the meeting directly. Overrides room settings. | `false` |
| `name` | string | NO | Name of the user. Used with `autoJoin` -- set `autoJoin: true` and provide a `name` to auto-join with that display name. | -- |
| `accessToken` | string | NO | Access token for authenticated joining (required for private rooms). Generate via the Video SDK REST API: `POST https://<appname>.metered.live/api/v1/token?secretKey=<key>` with body `{ "roomName": "...", "expirationDate": "ISO date" }`. Used with `autoJoin`. | -- |
| `joinVideoOn` | boolean | NO | Whether the camera is on when the user joins. Overrides room settings. | `true` |
| `joinAudioOn` | boolean | NO | Whether the microphone is on when the user joins. Overrides room settings. | `true` |
| `showInviteBox` | boolean | NO | When only one participant is in the meeting, an invite box with instructions is shown. Set to `false` to hide it. | `true` |
| `disableScreenSharing` | boolean | NO | Disables screen sharing for this embed instance. Cannot override room settings if already disabled there. | `false` |
| `disableChat` | boolean | NO | Disables chat for this embed instance. Overrides room settings for this specific embed. | `false` |

Example with multiple options:

```javascript
var frame = new MeteredFrame();
frame.init({
    roomURL: "yourappname.metered.live/my-room",
    width: "100%",
    height: "800px",
    autoJoin: true,
    name: "James Bond",
    joinVideoOn: false,
    joinAudioOn: true,
    disableChat: false,
    disableScreenSharing: false,
    showInviteBox: false,
}, document.getElementById("metered-frame"));
```

## Methods

### init(options, domElement)

Initializes and mounts the Metered Embed iframe. This method MUST be called -- the iframe is not mounted until `init()` is called. You can call it on page load or after a user interaction if you want the embed to appear on demand.

**Parameters:**

- `options` (Object, required) -- The init options object (see Init Options section above).
- `domElement` (HTMLElement, required) -- The DOM element where the iframe will be mounted.

**Returns:** void

```javascript
var frame = new MeteredFrame();
frame.init({
    roomURL: "appname.metered.live/my-room",
}, document.getElementById("metered-frame"));
```

### join(options)

Joins the participant to the meeting programmatically. Must be called after `init()`. Used when `autoJoin` is `false` and you want to trigger joining from your application code.

**Parameters:**

- `options` (Object, required) -- Must contain either `name` or `accessToken`.
  - `name` (string) -- Display name for the participant.
  - `accessToken` (string) -- Access token for authenticated joining.

**Returns:** void

Join by name:

```javascript
frame.join({
    name: "James Bond"
});
```

Join by access token:

```javascript
frame.join({
    accessToken: "..."
});
```

### leave()

Exits the meeting. Must be called after `join()`. Behaves the same as pressing the end-call button in the meeting frame.

**Parameters:** none

**Returns:** void

```javascript
frame.leave();
```

### openChat()

Opens the chat panel in the iframe. Only works when chat is enabled in the room settings. Behaves the same as pressing the chat button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.openChat();
```

### closeChat()

Closes the visible chat panel in the iframe. Behaves the same as pressing the close-chat button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.closeChat();
```

### startCamera()

Starts sharing the participant's camera in the meeting. Behaves the same as pressing the camera button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.startCamera();
```

### stopCamera()

Stops sharing the participant's camera. Behaves the same as pressing the stop-camera button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.stopCamera();
```

### startScreenShare()

Starts screen sharing. Behaves the same as pressing the share-screen button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.startScreenShare();
```

### stopScreenShare()

Stops screen sharing.

**Parameters:** none

**Returns:** void

```javascript
frame.stopScreenShare();
```

## Events

The Metered Embed Frame SDK emits events that you can listen to using `frame.on()`.

**Listener pattern:**

```javascript
frame.on("<eventName>", function(data) {
    // Handle event
});
```

### ready

Emitted when the Metered Frame iframe has loaded and is ready for interaction. No callback data is passed.

```javascript
frame.on("ready", function() {
    console.log("Metered Frame is ready");
});
```

### meetingJoined

Emitted when the current user successfully joins the meeting.

```javascript
frame.on("meetingJoined", function(meetingInfo) {
    console.log("Joined the meeting", meetingInfo);
});
```

### meetingLeft

Emitted when the current user leaves the meeting.

```javascript
frame.on("meetingLeft", function(meetingLeft) {
    console.log("Left the meeting");
});
```

### onlineParticipants

Emitted multiple times during the meeting. Contains an array of all participants currently in the meeting.

```javascript
frame.on("onlineParticipants", function(onlineParticipants) {
    console.log("Current participants:", onlineParticipants);
});
```

**Callback data:** `onlineParticipants` is an array of objects. Each object has:

| Property | Type | Description |
|---|---|---|
| `_id` | string | Participant session ID. |
| `name` | string | Display name of the user. |
| `sharingAudio` | boolean | Whether the user is currently sharing their microphone. |
| `sharingVideo` | boolean | Whether the user is currently sharing their camera. |
| `sharingScreen` | boolean | Whether the user is currently sharing their screen. |
| `disabledAudio` | boolean | Whether an admin has disabled the user's audio. |
| `disabledScreenSharing` | boolean | Whether an admin has disabled the user's screen sharing. |
| `disabledVideo` | boolean | Whether an admin has disabled the user's camera. |
| `isAdmin` | boolean | Whether the user is an admin. |
| `meetingSessionId` | string | The meeting session ID. |
| `roomId` | string | The room ID. |

### participantJoined

Emitted when a new participant joins the meeting.

```javascript
frame.on("participantJoined", function(participantInfo) {
    console.log("Participant joined:", participantInfo.name);
});
```

**Callback data:** `participantInfo` is an object with the same shape as each entry in the `onlineParticipants` array (see above): `_id`, `name`, `sharingAudio`, `sharingVideo`, `sharingScreen`, `disabledAudio`, `disabledScreenSharing`, `disabledVideo`, `isAdmin`, `meetingSessionId`, `roomId`.

### participantLeft

Emitted when a participant leaves the meeting. Callback data has the same shape as `participantJoined`.

```javascript
frame.on("participantLeft", function(participantInfo) {
    console.log("Participant left:", participantInfo.name);
});
```

### participantSharingStateUpdated

Emitted when a participant's sharing state changes (starts/stops camera, microphone, or screen share).

```javascript
frame.on("participantSharingStateUpdated", function(participantSharingState) {
    console.log("Sharing state changed:", participantSharingState.action);
});
```

**Callback data:** `participantSharingState` is an object with:

| Property | Type | Description |
|---|---|---|
| `action` | string (enum) | The action taken. One of: `startedSharingScreen`, `stoppedSharingScreen`, `startedSharingVideo`, `stoppedSharingVideo`, `startedSharingAudio`, `stoppedSharingAudio`. |
| `eventId` | string | Unique event ID for this action. |
| `participantSessionId` | string | The participant's session ID. |
| `sharingAudio` | boolean | Whether the user is currently sharing their microphone. |
| `sharingVideo` | boolean | Whether the user is currently sharing their camera. |
| `sharingScreen` | boolean | Whether the user is currently sharing their screen. |
| `disabledAudio` | boolean | Whether an admin has disabled the user's audio. |
| `disabledScreenSharing` | boolean | Whether an admin has disabled the user's screen sharing. |
| `disabledVideo` | boolean | Whether an admin has disabled the user's camera. |
| `meetingSessionId` | string | The meeting session ID. |

## iFrame Options

These are room-level configuration options set in the Metered Dashboard when creating or editing a room. They control the default behavior of the embedded meeting for all participants.

### Camera on join

When enabled, the participant's camera is automatically shared when they join the meeting. Used in conjunction with Auto Join. Users can still toggle their camera after joining. Can be overridden per-embed using the `joinVideoOn` init option.

### Microphone on join

When enabled, the participant's microphone is automatically shared when they join the meeting. Can be overridden per-embed using the `joinAudioOn` init option.

### Screen Sharing

When enabled, users can share their screen. When disabled, the screen-sharing button is hidden for all users. To disable screen sharing for specific users only, use the `disableScreenSharing` init option in the Embed Frame SDK.

### Text Chat

When enabled, users can text chat with each other. When disabled, text chat is not available in the meeting. To disable chat for specific users only, use the `disableChat` init option in the Embed Frame SDK.

### New Chat For Meeting Session

When enabled, a new chat room is created for each meeting session with separate chat history. When disabled, the chat is associated with the room itself, and all meeting sessions of that room share the same chat history.

### Request to Join

When the room privacy setting is set to `private` and Request to Join is enabled, users who do not have an `accessToken` can request to join the meeting. A notification is sent to the meeting admin, and when the admin accepts the request, the user is allowed to join.

### Show Invite Instruction

When there is only one participant in a meeting, invite instructions are displayed showing the meeting URL. Disabling this option hides the invite instructions. Can be overridden per-embed using the `showInviteBox` init option.

### Auto Join

When enabled, the Lobby / Join Meeting page is not displayed and the user directly enters the meeting. Can be overridden per-embed using the `autoJoin` init option.

### Admin Only Broadcast

When enabled, only admins can share their camera, microphone, and screen by default. Admins can selectively allow specific participants to share their camera, microphone, or screen during the meeting. All non-admin participants are view-only by default.

## Complete Example

```html
<div id="metered-frame"></div>
<button id="join-btn">Join</button>
<button id="leave-btn">Leave</button>

<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
<script>
var frame = new MeteredFrame();

frame.init({
    roomURL: "yourappname.metered.live/my-room",
    autoJoin: false,
    joinVideoOn: true,
    joinAudioOn: true,
}, document.getElementById("metered-frame"));

frame.on("ready", function() { console.log("Frame ready"); });
frame.on("meetingJoined", function(info) { console.log("Joined", info); });
frame.on("meetingLeft", function() { console.log("Left meeting"); });
frame.on("onlineParticipants", function(list) { console.log(list.length, "online"); });
frame.on("participantJoined", function(p) { console.log(p.name, "joined"); });
frame.on("participantLeft", function(p) { console.log(p.name, "left"); });
frame.on("participantSharingStateUpdated", function(s) { console.log(s.action); });

document.getElementById("join-btn").onclick = function() { frame.join({ name: "User" }); };
document.getElementById("leave-btn").onclick = function() { frame.leave(); };
</script>
```