ChatGPT Apps SDK Hooks

The ChatGPT Apps SDK provides a set of React hooks for building widgets that run inside ChatGPT. These hooks enable your widget to communicate with the host ChatGPT environment, manage display modes, send messages, and more.

Installation

npm install @chatgpt-apps/sdk

Available Hooks

Hook	Description
useWidgetProps	Access props passed to your widget from the host
useDisplayMode	Get the current display mode (pip, inline, fullscreen)
useMaxHeight	Get the maximum height available for your widget
useCallTool	Call tools/functions defined by the host
useSendMessage	Send messages back to the ChatGPT conversation
useOpenExternal	Open external URLs in a new browser tab
useRequestDisplayMode	Request a change to the widget's display mode
useOpenAIGlobal	Access global OpenAI context and utilities

Usage Example

import {
  useWidgetProps,
  useDisplayMode,
  useSendMessage,
} from '@chatgpt-apps/sdk';

function MyWidget() {
  const props = useWidgetProps();
  const displayMode = useDisplayMode();
  const sendMessage = useSendMessage();

  const handleClick = () => {
    sendMessage({
      type: 'text',
      content: 'Button clicked in widget!',
    });
  };

  return (
    <div>
      <p>Display mode: {displayMode}</p>
      <button onClick={handleClick}>Send Message</button>
    </div>
  );
}

TypeScript Support

All hooks are fully typed with TypeScript. Import types from the SDK:

import type {
  WidgetProps,
  DisplayMode,
  MessagePayload,
} from '@chatgpt-apps/sdk';

Error Handling

Hooks may throw errors if used outside of a valid ChatGPT Apps SDK context. Wrap your widget with the SDK provider:

import { ChatGPTAppsProvider } from '@chatgpt-apps/sdk';

function App() {
  return (
    <ChatGPTAppsProvider>
      <MyWidget />
    </ChatGPTAppsProvider>
  );
}

Hooks Overview