Overview
These hooks wrap the ChatGPTwindow.openai runtime APIs, providing typed React hooks for host-specific features that go beyond the MCP Apps standard. They are available only when running inside ChatGPT (or the inspector with the ChatGPT host selected).
Import
Feature Detection Pattern
useUploadFile
Upload a file from the app UI into the ChatGPT conversation.Signature
Returns
(file: File) => Promise<CreateFileResult>
Async function that uploads a file and returns its ID.
CreateFileResult
string
required
The ID of the uploaded file.
Supported Formats
image/png, image/jpeg, image/webp
Usage
useRequestModal
Open a host-controlled modal in ChatGPT.Signature
OpenModalParams
string
URL of an alternate UI template to load in the modal. Omit to reuse the current UI.
Record<string, unknown>
Arbitrary params forwarded to the modal content.
Usage
useRequestCheckout
Trigger the ChatGPT instant checkout flow.Signature
CheckoutSession
string
required
Unique session ID.
CheckoutPaymentProvider
required
Payment provider configuration.
'ready_for_payment'
required
Must be
'ready_for_payment' to initiate checkout.string
required
ISO 4217 currency code (e.g.
'USD').CheckoutTotal[]
required
Line items and totals.
CheckoutLink[]
required
Legal links shown during checkout.
'live' | 'test'
required
Whether to use live or test payment processing.
CheckoutOrder
string
required
Order ID.
string
required
ID of the checkout session that produced this order.
'completed' | string
required
Order status.
string
Optional permalink to the order receipt.
Usage
Low-Level Access
For advanced use cases, you can access thewindow.openai runtime directly:
Inspector Support
When the ChatGPT host is selected in the Inspector, a mockwindow.openai runtime is automatically injected into the iframe. This makes isChatGPT() return true and all ChatGPT hooks functional with stub implementations that log to the browser console.
When a different host (e.g. Claude) is selected, window.openai is not injected and isChatGPT() returns false.
See Also
Host Detection
Detect which host is running your app.
Inspector
Test ChatGPT hooks locally with the mock runtime.