Setting the file. One moment.
Subchapter 2.7
references/window-openai-patterns.mdMarkdown5 KBView on GitHub
Load this reference when a task needs ChatGPT-only widget features, when translating older examples that use an app wrapper, or when a React widget should read host globals safely.
ui/* notifications, tools/call, , and .ui/messageui/update-model-contextwindow.openai only when the task specifically benefits from ChatGPT-only runtime conveniences.window.openai as additive. The app should still have a coherent baseline path on the MCP Apps standard when possible.window.openai.toolInput: tool arguments supplied by the hostwindow.openai.toolOutput: current structuredContentwindow.openai.toolResponseMetadata: current _meta payload (widget-only)window.openai.widgetState: persisted widget-local snapshotwindow.openai.setWidgetState(state): persist widget-local snapshot after meaningful UI changeswindow.openai.callTool(name, args): call another MCP tool from the widgetwindow.openai.sendFollowUpMessage({ prompt, scrollToBottom? }): ask ChatGPT to post a widget-authored follow-up messagewindow.openai.openExternal({ href, redirectUrl? }): open an external URL through ChatGPT’s vetted flowwindow.openai.requestDisplayMode({ mode }): request inline, pip, or fullscreenwindow.openai.requestModal({ params, template? }): open a host-owned modalwindow.openai.requestClose(): ask ChatGPT to close the widgetwindow.openai.uploadFile(file, options?): upload a file from the widgetwindow.openai.selectFiles(): open ChatGPT’s file library picker and return app-authorized fileswindow.openai.getFileDownloadUrl({ fileId }): resolve a temporary download URLwindow.openai.notifyIntrinsicHeight(...): report dynamic height changeswindow.openai.setOpenInAppUrl({ href }): override the fullscreen punch-out targetwindow.openai.themewindow.openai.displayModewindow.openai.maxHeightwindow.openai.safeAreawindow.openai.viewwindow.openai.userAgentwindow.openai.localeapp.callServerTool({ name, arguments }):
Use window.openai.callTool(name, args) when you intentionally want the ChatGPT compatibility layer.
Use tools/call over the bridge when you want the portable MCP Apps path.app.sendMessage(...):
Use ui/message for portable bridge messaging.
If the task is intentionally ChatGPT-specific, window.openai.sendFollowUpMessage({ prompt }) is the closest supported path.app.updateModelContext(...):
Use ui/update-model-context over the bridge.
This is part of the standard bridge, not a window.openai feature.app.openLink({ url }):
Use window.openai.openExternal({ href: url }) when you intentionally want ChatGPT’s external navigation flow.app.requestDisplayMode({ mode }):
Use window.openai.requestDisplayMode({ mode }).app.getHostContext():
Read the documented globals directly (theme, displayMode, locale, maxHeight, safeArea, userAgent).app.getHostCapabilities() / app.getHostVersion():
These are wrapper-level convenience APIs.
Prefer feature detection (if (window.openai?.requestModal)) and the documented globals instead of teaching these as the primary public surface.window.openai.uploadFile(file) when the user is adding a new local file inside the widget.window.openai.uploadFile(file, { library: true }) when the upload should also be saved into the user’s ChatGPT file library.window.openai.selectFiles() when the user should be able to reuse files that are already in their ChatGPT file library instead of uploading again.window.openai.getFileDownloadUrl({ fileId }) when the widget needs a temporary URL for previewing a file or forwarding it through a file-param payload.if (window.openai?.selectFiles)) and provide a fallback upload flow when a ChatGPT-only helper is unavailable.src/use-openai-global.ts is a good baseline for subscribing to host global changes without scattering direct window.openai reads through components.src/use-widget-state.ts is a good baseline for mirroring React state into window.openai.setWidgetState(...).src/use-widget-props.ts is a good baseline for reading typed toolOutput with a local fallback.