Client API reference

This reference describes host interfaces available in official releases, with version differences noted in the relevant sections. See the Client API guide for examples and Capabilities and progress for version support.

Entry and availability

const miniapp = window.mcode?.miniapp;

The host injects window.mcode into a managed Mini App’s main page through preload. No runtime SDK or plugin ID is required. Ordinary browsers, other pages, and older hosts may omit these objects, so check before calling.The v3.1.6 main page exposes the namespaces below. Presence does not establish a manifest declaration or an enabled permission: permission-protected calls are checked against page identity, declarations, and switches. Node uses the separate Node API.

Member	Page entry	Purpose
`message`	`miniapp.message.append`	Append to the message draft after confirmation
`window`	`miniapp.window`	This page’s window handle; experimental
`speech`	`miniapp.speech.transcribe`	Host speech transcription
`tool`	`miniapp.tool.request`	Request tool permission ahead of time; no page `list` or `call`
`agent`	`miniapp.agent`	Page Agent API; see the full reference
`capabilities`	`miniapp.capabilities.has`	Synchronous host interface detection

Page async APIs reject with a lowercase code in Error.message. Do not rely on Node-style code, retryable, or disposition fields; see the page error convention.

message.append

interface MiniAppMessageAPI {
  append(text: string): Promise<void>;
}

Parameter	Type	Description
`text`	`string`	Plain text, up to 100,000 UTF-16 code units; preserves spaces, tabs, and newlines. HTML is treated as text

Every call opens host confirmation, with no remembered choice. Even an empty string needs confirmation, but leaves the draft unchanged. After confirmation, the host preserves existing text, references, and attachments, and appends the new text. Resolution means the append completed, not that a message was sent or an Agent ran.The target is the local, writable session containing the page. An unavailable target does not fall back to another session, a home draft, or a new session. This API grants no session reads and cannot change sent messages. There is no page cancellation parameter; the user can refuse the confirmation. After result_unknown, inspect the input before deciding to retry.Errors are user_cancelled, invalid_request, text_too_large, not_allowed, target_unavailable, and result_unknown; see Error codes.

window

The window handle interface may change, so feature-detect before use. It controls only its calling page’s window. id is a stable opaque string, not a session or run ID; popping out or returning to the file panel does not change it.

interface MiniAppWindowHandle {
  readonly id: string;
  getState(): Promise<MiniAppWindowState>;
  update(patch: MiniAppWindowPatch): Promise<MiniAppWindowState>;
  focus(): Promise<void>;
  onDidChangeState(
    listener: (state: MiniAppWindowState) => void,
  ): { dispose(): void };
}

type MiniAppWindowState =
  | { readonly mode: 'inline'; readonly modeChangeReloadsPage?: boolean }
  | {
      readonly mode: 'window';
      readonly window: MiniAppWindowOptions;
      readonly modeChangeReloadsPage?: boolean;
    };

State fields

getState() takes no arguments. inline means the page is in the file panel, with no window field. window means a separate window, with every field below.Either state may also return a top-level modeChangeReloadsPage field indicating whether a mode change rebuilds the page; see Page rebuilds and confirmation.

`window` field	Type	Meaning
`width` / `height`	`number`	Content size, using the same dimensions as updates
`minWidth` / `minHeight`	`number`	Manifest minimum size, defaulting to 480 and 360 respectively
`x` / `y`	`number`	Screen coordinates of the content area, not the outer frame
`visible`	`boolean`	Whether the window is visible
`resizable`	`boolean`	Whether the current window can be resized
`frame`	`boolean`	Whether it has a system frame
`transparent`	`boolean`	Whether it uses a transparent window
`alwaysOnTop`	`boolean`	Whether it stays on top
`clickThrough`	`boolean`	Whether mouse events pass through
`skipTaskbar`	`boolean`	Whether it is hidden from the taskbar

update(patch)

interface MiniAppWindowPatch {
  readonly mode?: 'inline' | 'window';
  readonly width?: number;
  readonly height?: number;
  readonly x?: number;
  readonly y?: number;
  readonly visible?: boolean;
  readonly resizable?: boolean;
  readonly alwaysOnTop?: boolean;
  readonly clickThrough?: boolean;
  readonly skipTaskbar?: boolean;
}

A successful reply contains the full MiniAppWindowState. All fields are optional; omitted or undefined fields remain unchanged, and an empty object is valid. Unknown fields, wrong types, and non-finite numbers fail with invalid_request. In v3.1.10, cancelling window-transfer confirmation resolves with the current state and the original mode: a successful reply does not prove that the requested mode took effect. See Page rebuilds and confirmation.

Field or action	Rule
`mode`	Only `inline` or `window`. Even setting the current mode requires a user gesture while `navigator.userActivation.isActive` is `true`
`width` / `height`	Finite numbers greater than 0 and no greater than 10,000; rounded and clamped to the minimum size when applied. Programmatic resizing is refused when the manifest or the resulting window disallows it
`x` / `y`	Finite numbers from −100,000 to 100,000; rounded when applied
`alwaysOnTop: true` / `clickThrough: true`	The manifest’s `surface.window` must already declare the corresponding field `true`; switching it off does not need that ceiling
`visible`	Hiding does not itself close the page; scripts, timers, and network requests keep running. Showing without a user gesture does not actively take focus
`frame`, `transparent`, `minWidth`, `minHeight`	Manifest-only construction options; including them in a runtime patch gives `not_permitted`
Inline state	If the target remains `inline`, fields other than `mode` give `inline_mode`

When updating x, y, width, or height, the host checks the final content rectangle after rounding and applying minimum dimensions. It must overlap the same display work area by at least 40 px on both axes; otherwise the update fails with not_permitted. This rule also applies to size-only updates, not just window moves.Updates without mode in the same animation frame are merged, with later fields winning. All callers in that frame share one result or rejection. A mode update is sent immediately to preserve its user gesture.

focus()

Takes no arguments and returns Promise<void>. A user gesture is required. A separate window is restored from minimization, shown, and focused; an inline page requests host focus and selects its own tab. Do not rely on it to expand a collapsed file panel. It does not create a page or control another Mini App.

onDidChangeState(listener)

Synchronously returns { dispose() }. A non-function listener synchronously throws Error('invalid_request'). An update() delivers state if the current document remains alive and receives a successful reply. This does not prove that mode changed; inspect the delivered state. While the document remains alive, periodic checks detect external changes such as dragging a window, with no guarantee of every intermediate state. Initial subscription does not immediately deliver an initial value; call getState() for one.Call dispose() to unsubscribe; leaving the page also clears listeners. A throwing listener does not interrupt a window update. Window errors are inline_mode, not_permitted, busy, result_unknown, and invalid_request. After result_unknown, use getState() to reconcile; see Window errors.

Page rebuilds and confirmation

Official releases from v3.1.9 may return the optional modeChangeReloadsPage?: boolean field. Check the runtime result of getState(); this field is not an update patch option. When it is true, an actual change between inline and window rebuilds the page. Hosts that move the native page do not return this flag, so not every window transfer reloads the page.A rebuild preserves the logical window ID and Node service, but the current document, JavaScript memory, media streams, page subscriptions, and pending page Promises do not survive. Save necessary state first. Do not put required work after await update({ mode }) or wait for the old document’s onDidChangeState to confirm completion. When the destination document starts, call getState(), restore saved content, and subscribe again. An absent flag does not guarantee that a host reload, crash, or another page-ending event cannot end the document.From v3.1.10, popping out or returning a page that requires rebuilding first displays the impact in the main host window and waits for user confirmation. Closing the separate window or pressing Cmd/Ctrl+W uses the same flow; the original window is not hidden or destroyed while waiting. Cancellation leaves the page, requests, and window intact. update() resolves with the current state, whose mode may still be the original value, rather than rejecting with user_cancelled. After confirmation, the old page’s requests and subscriptions are cancelled or cleaned up when the page ends. Completed operations are not undone, and requests are not replayed automatically.

speech.transcribe

interface MiniAppSpeechAudioFormat {
  readonly sampleRate: 16000;
  readonly channelCount: 1;
  readonly sampleFormat: 's16';
}

interface MiniAppSpeechTranscribeInput {
  readonly audio: ArrayBuffer | ArrayBufferView;
  readonly format: MiniAppSpeechAudioFormat;
}

interface MiniAppSpeechTranscribeOptions {
  readonly onPartial?: (text: string) => void;
}

interface MiniAppSpeechAPI {
  transcribe(
    input: MiniAppSpeechTranscribeInput,
    options?: MiniAppSpeechTranscribeOptions,
  ): Promise<{ readonly text: string }>;
}

Parameter	Description
`input.audio`	One raw PCM utterance: at least one sample, an even byte count, and at most 16,000,000 bytes (500 seconds). Accepts `Int16Array`, `ArrayBuffer`, or a view over an ordinary `ArrayBuffer`; shared buffers are refused
`input.format`	Exactly the three fields and values above: 16 kHz, mono, signed 16-bit little-endian PCM. Other rates, channels, or extra format fields are refused
`options.onPartial`	Optional callback receiving intermediate text while the host transcribes; returned `text` is final. A callback error is logged to the page console and does not stop transcription

Declare deviceAccess: ["microphone"] and keep its switch on. The page captures audio, chooses the utterance boundary, converts samples, and stops all media tracks. The host transcribes the complete utterance; onPartial is not live recognition while recording. Do not pass WAV, WebM, Ogg, FLAC, MP3, or MediaRecorder output directly.Only one transcription per Mini App can run at once; another gets busy. There is no page signal or cancel() parameter. Ending the page aborts the in-flight transcription, and host processing has a 180-second deadline. Switching microphone access off refuses later calls without forcibly stopping a media stream the page already owns.Errors are invalid_request, not_permitted, audio_too_large, busy, runtime_unavailable, transcription_failed, and result_unknown; see Speech errors. See the guide for recording examples.

tool.request

interface MiniAppToolRequestAPI {
  request(
    names: readonly string[],
  ): Promise<Record<string, 'allow' | 'ask' | 'deny'>>;
}

Parameter or return	Description
`names`	1–10 distinct, nonempty runtime tool names, each at most 1,024 UTF-8 bytes. Obtain them from Node `context.tool.list()` and pass them to the page through a business endpoint; never construct them
Return	A permission snapshot keyed by the requested names: `allow` permits a call, `ask` still needs confirmation, and `deny` currently refuses it. This is not an authorization credential for later calls

Declare toolAccess: ["call"], keep the Node service running, and invoke directly from a user gesture. The host asks only about tools still at ask, letting the user tick which to always allow. Leaving a box unticked or refusing does not necessarily reject the entire request: it returns actual permissions. Entries already allow or deny are not changed by this request.When the tool-calling switch is off, the method returns deny for every requested name without a prompt. Without toolAccess there is no usable tool session; an unavailable Node tool session or channel rejects with runtime_unavailable. The page has neither tool list() nor call(), nor a cancellation parameter for this method. Actual calls use the Node tool API, and the host judges permission again on every call.Errors are invalid_request, not_permitted, approval_required, runtime_unavailable, and result_unknown; see Tool permission errors. Read the rejection’s Error.message; do not rely on the permissions field attached to Node-side errors.

capabilities.has

interface MiniAppHostCapabilities {
  has(name: string): boolean;
}

Returns a boolean synchronously without asking for permission or making an async host call. Unknown names return false; a non-string passed at runtime also returns false. Older hosts may omit capabilities, so use miniapp?.capabilities?.has(name).This table lists all 14 names in v3.1.6. It is fixed per host version and shared by the page and Node. true means the host implements the feature, not that the current side has that object, the manifest declared it, or the user granted it.

Name	Page entry (after `miniapp.`)	Node entry
`agent.agents`	`agent.agents()`	`context.agent.agents()`
`agent.create`	`agent.create()`	`context.agent.create()`
`agent.models`	`agent.models()`	`context.agent.models()`
`agent.observe`	`agent.observe()`	`context.agent.observe()`
`agent.open`	`agent.open()`	None
`agent.run`	`agent.run()`	`context.agent.run()`
`agent.session`	`agent.session()`	`context.agent.session(id)`
`agent.sessions`	`agent.sessions()`	`context.agent.sessions()`
`hostConnector`	None	`context.hostConnector`
`message.append`	`message.append()`	None
`speech.transcribe`	`speech.transcribe()`	None
`tool`	No list or call entry	`context.tool`
`tool.request`	`tool.request()`	`context.tool.request()`
`window`	`window` handle	None

agent.reply, agent.answer, and agent.cancel are not separate capability names; do not probe those names to infer method support. Check each API’s availability and permission requirements as well.

Agent namespace

For page miniapp.agent methods (run, reply, answer, cancel, open, catalogs, and session observation), including parameter differences from Node, see the Agent API reference.

Camera and system notifications

These capabilities are supported from MiniMax Code v3.1.9. They use standard browser APIs, with no new host namespace or capability-detection name. Declare the minimum version in engines.mcode and the required items in deviceAccess; users can turn access off in plugin details.

Declaration	Page operation	Conditions
`camera`	`navigator.mediaDevices.getUserMedia({ video: true })`	Camera is declared and enabled; the operating system may also require permission
`notifications`	`new Notification(...)`	Notifications are declared and enabled; the creating page handles the notification

A combined audio/video request requires both microphone and camera to be declared and enabled. Turning a permission off blocks new capture requests; the page must still stop media streams it already holds. Standard capture errors, such as NotAllowedError, come from the browser API and do not use host speech-transcription error codes.A notification click handler can call the window handle’s focus() while the original page remains alive. Do not rely on it to expand a collapsed file panel. After that page closes or reloads, an old notification cannot reopen it. This API does not provide background notifications after the page closes.See the Camera and System notifications guides for examples and limits.

Get started

Learn

Develop

Reference

Entry and availability

message.append

window

State fields

update(patch)

focus()

onDidChangeState(listener)

Page rebuilds and confirmation

speech.transcribe

tool.request

capabilities.has

Agent namespace

Camera and system notifications

​Entry and availability

​message.append

​window

​State fields

​update(patch)

​focus()

​onDidChangeState(listener)

​Page rebuilds and confirmation

​speech.transcribe

​tool.request

​capabilities.has

​Agent namespace

​Camera and system notifications

Entry and availability

message.append

window

State fields

update(patch)

focus()

onDidChangeState(listener)

Page rebuilds and confirmation

speech.transcribe

tool.request

capabilities.has

Agent namespace

Camera and system notifications