Skip to main content

​
Overview

The useWidgetAPI hook provides access to the widget runtime API, which includes methods for calling tools, sending messages, and controlling the widget display.

​
Import

import { useWidgetAPI } from 'sunpeak';

​
Signature

function useWidgetAPI(): WidgetAPI | null

​
Returns

​
return
WidgetAPI | null
The API object with methods, or null if not available.

​
API Methods

​
callTool
(name: string, args: unknown) => Promise<unknown>
Invoke an MCP tool.
​
sendFollowUpMessage
({ prompt }: { prompt: string }) => void
Send a follow-up message to the chat.
​
openExternal
({ href }: { href: string }) => void
Open an external URL.
​
requestDisplayMode
({ mode }: { mode: DisplayMode }) => void
Request a display mode change.
​
requestModal
({ mode, params }: { mode: string, params?: Record<string, unknown> }) => void
Request modal view.
​
notifyIntrinsicHeight
(height: number) => void
Notify the platform of content height.

​
Usage

import { useWidgetAPI } from 'sunpeak';

function MyWidget() {
  const api = useWidgetAPI();

  const handleAction = async () => {
    if (api) {
      const result = await api.callTool('my-tool', { arg: 'value' });
      console.log(result);
    }
  };

  return <button onClick={handleAction}>Call Tool</button>;
}