API Reference

useChat<TPart, TEvent>(options): UseChatReturn<TPart>

The hook accepts two optional generic parameters:

• TPart — custom content part types. Defaults to ContentPart (TextPart | ToolCallPart).
• TEvent — custom SSE event types. Defaults to SSEEvent (TextDeltaEvent | ToolCallEvent).

// Default — uses built-in ContentPart and SSEEvent
const chat = useChat({ api: "/chat" });

// Custom parts — extend with your own part types
const chat = useChat<ContentPart | ThinkingPart>({ api: "/chat" });

// Custom parts and events — extend both
const chat = useChat<ContentPart | ErrorPart, SSEEvent | ErrorEvent>({
  api: "/chat",
  onEvent: (event, helpers) => {
    // event is typed as SSEEvent | ErrorEvent
  },
});

Options

Option	Type	Required	Description
api	string	Yes	SSE endpoint URL
initialMessages	Message<TPart>[]	No	Initial messages to prepopulate the chat
headers	Record<string, string>	No	Extra headers merged into every fetch request
body	Record<string, unknown>	No	Extra fields merged into POST body alongside message
onEvent	(event: TEvent, helpers) => void	No	Custom SSE event handler (replaces default text_delta handling)
onMessage	(message) => void	No	Called when a complete message (user or assistant) is added
onError	(error) => void	No	Called on fetch or stream error
onFinish	(messages) => void	No	Called when the stream ends

Return Value

Field	Type	Description
messages	Message<TPart>[]	Array of { id, role, parts }
isLoading	boolean	true while streaming
error	Error | null	Most recent error, or null
sendMessage	(text: string) => void	Send a user message and start streaming
stop	() => void	Abort the current stream
setMessages	Dispatch<SetStateAction<Message<TPart>[]>>	Direct state setter for programmatic control

Types

All types are exported for use in your own code:

import type {
  TextPart,
  ToolCallPart,
  ContentPart,
  Message,
  SSEEvent,
  TextDeltaEvent,
  ToolCallEvent,
  EventHelpers,
  UseChatOptions,
  UseChatReturn,
} from "@devscalelabs/react-sse-chat";

TextPart

interface TextPart {
  type: "text";
  text: string;
}

ToolCallPart

interface ToolCallPart {
  type: "tool_call";
  tool_name: string;
  argument: string;
  callId?: string; // present in agent history, absent during SSE streaming
}

ContentPart

Built-in content part union. Use as a base when defining custom parts:

type ContentPart = TextPart | ToolCallPart;

Message<TPart>

Generic over part type. Defaults to ContentPart:

interface Message<TPart extends { type: string } = ContentPart> {
  id: string;
  role: "user" | "assistant";
  parts: TPart[];
}

SSEEvent

type SSEEvent = TextDeltaEvent | ToolCallEvent;

TextDeltaEvent

interface TextDeltaEvent {
  type: "text_delta";
  delta: string;
}

ToolCallEvent

interface ToolCallEvent {
  type: "tool_call";
  tool_name: string;
  argument: string;
}

EventHelpers<TPart>

Generic over part type. Defaults to ContentPart:

interface EventHelpers<TPart extends { type: string } = ContentPart> {
  appendText: (delta: string) => void;
  appendPart: (part: TPart) => void;
  setMessages: Dispatch<SetStateAction<Message<TPart>[]>>;
}

UseChatOptions<TPart, TEvent>

Generic over part type and event type. Defaults to ContentPart and SSEEvent:

interface UseChatOptions<
  TPart extends { type: string } = ContentPart,
  TEvent extends { type: string } = SSEEvent,
> {
  api: string;
  initialMessages?: Message<TPart>[];
  headers?: Record<string, string>;
  body?: Record<string, unknown>;
  onEvent?: (event: TEvent, helpers: EventHelpers<TPart>) => void;
  onFinish?: (messages: Message<TPart>[]) => void;
  onMessage?: (message: Message<TPart>) => void;
  onError?: (error: Error) => void;
}

UseChatReturn<TPart>

Generic over part type. Defaults to ContentPart:

interface UseChatReturn<TPart extends { type: string } = ContentPart> {
  messages: Message<TPart>[];
  isLoading: boolean;
  error: Error | null;
  sendMessage: (text: string) => void;
  stop: () => void;
  setMessages: Dispatch<SetStateAction<Message<TPart>[]>>;
}

---

convertOpenAIAgentsMessages(items, options?)

Converts an array of raw OpenAI Agents SDK message items into Message<OpenAIAgentsContentPart>[]. Consecutive assistant-side items are merged into a single message with multiple parts.

import { convertOpenAIAgentsMessages } from "@devscalelabs/react-sse-chat";

const messages = convertOpenAIAgentsMessages(agentData);
const messagesWithReasoning = convertOpenAIAgentsMessages(agentData, {
  includeReasoning: true,
});

ConvertOpenAIAgentsOptions

interface ConvertOpenAIAgentsOptions {
  /** Include reasoning items as ReasoningPart. Defaults to false. */
  includeReasoning?: boolean;
}

OpenAI Agents Types

ReasoningPart

interface ReasoningPart {
  type: "reasoning";
  text: string;
}

ToolResultPart

interface ToolResultPart {
  type: "tool_result";
  callId: string;
  output: string;
}

OpenAIAgentsContentPart

Union of all content parts the converter can produce:

type OpenAIAgentsContentPart =
  | TextPart
  | ToolCallPart
  | ReasoningPart
  | ToolResultPart;