UseChatStorageResult

options?

CreateConversationOptions

searchOptions?

Partial<MemoryRetrievalSearchOptions>

Optional search configuration (limit, minSimilarity, etc.)

id

string

options?

object

options.conversationId?

string

options.limit?

number

id

string

conversationId

string

args

object

‐

args.apiType?

ApiType

Override the API type for this specific request.

• “responses”: OpenAI Responses API (supports thinking, reasoning, conversations)
• “completions”: OpenAI Chat Completions API (wider model compatibility)

Useful when different models need different APIs within the same hook instance.

args.clientTools?

LlmapiChatCompletionTool[]

Client-side tools with optional executors. These tools run in the browser/app and can have JavaScript executor functions.

args.conversationId?

string

Explicitly specify the conversation ID to send this message to. If provided, bypasses the automatic conversation detection/creation. Useful when sending a message immediately after creating a conversation, to avoid race conditions with React state updates.

args.fileContext?

string

Additional context from preprocessed file attachments. Contains extracted text from Excel, Word, PDF, and other document files. Injected as a system message so it’s available throughout the conversation.

args.files?

FileMetadata[]

File attachments to include with the message (images, documents, etc.). Files with image MIME types and URLs are sent as image content parts. File metadata is stored with the message (URLs are stripped if they’re data URIs).

args.getThoughtProcess?

() => ActivityPhase[]

Callback to get activity phases AFTER streaming completes. Use this instead of thoughtProcess when phases are added dynamically during streaming (e.g., via server tool call events like “Searching…”, “Generating image…”).

If both thoughtProcess and getThoughtProcess are provided, getThoughtProcess takes precedence.

args.headers?

Record<string, string>

Custom HTTP headers to include with the API request. Useful for passing additional authentication, tracking, or feature flags.

args.includeHistory?

boolean

Whether to automatically include previous messages from the conversation as context. When true, fetches stored messages and prepends them to the request. Ignored if messages is provided.

Default

true

args.maxHistoryMessages?

number

Maximum number of historical messages to include when includeHistory is true. Only the most recent N messages are included to manage context window size.

Default

50

args.maxOutputTokens?

number

Maximum number of tokens to generate in the response. Use this to limit response length and control costs.

args.memoryContext?

string

Additional context from memory/RAG system to include in the request. Typically contains retrieved relevant information from past conversations.

args.messages

LlmapiMessage[]

The message array to send to the AI.

Uses the modern array format that supports multimodal content (text, images, files). The last user message in this array will be extracted and stored in the database.

When includeHistory is true (default), conversation history is prepended. When includeHistory is false, only these messages are sent.

Example

// Simple usage
sendMessage({
  messages: [
    { role: "user", content: [{ type: "text", text: "Hello!" }] }
  ]
})
 
// With system prompt and history disabled
sendMessage({
  messages: [
    { role: "system", content: [{ type: "text", text: "You are helpful" }] },
    { role: "user", content: [{ type: "text", text: "Question" }] },
  ],
  includeHistory: false
})
 
// With images
sendMessage({
  messages: [
    { role: "user", content: [
      { type: "text", text: "What's in this image?" },
      { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
    ]}
  ]
})

args.model?

string

The model identifier to use for this request (e.g., “gpt-4o”, “claude-sonnet-4-20250514”). If not specified, uses the default model configured on the server.

args.onData?

(chunk: string) => void

Per-request callback invoked with each streamed response chunk. Overrides the hook-level onData callback for this request only. Use this to update UI as the response streams in.

args.onThinking?

(chunk: string) => void

Per-request callback for thinking/reasoning chunks. Called with delta chunks as the model “thinks” through a problem. Use this to display thinking progress in the UI.

args.parentMessageId?

string

Parent message ID for branching (edit/regenerate). Sets on the user message.

args.reasoning?

LlmapiResponseReasoning

Reasoning configuration for o-series and other reasoning models. Controls reasoning effort level and whether to include reasoning summary.

args.searchContext?

string

Additional context from search results to include in the request. Typically contains relevant information from web or document searches.

args.serverTools?

ServerToolsFilter

Server-side tools to include from /api/v1/tools.

• undefined: Include all server-side tools (default)
• string[]: Include only tools with these names
• []: Include no server-side tools
• function: Dynamic filter that receives prompt embedding(s) and all tools, returns tool names to include. Useful for semantic tool matching.

Example

// Include only specific server tools
serverTools: ["generate_cloud_image", "perplexity_search"]
 
// Disable server tools for this request
serverTools: []
 
// Semantic tool matching based on prompt
serverTools: (embeddings, tools) => {
  const matches = findMatchingTools(embeddings, tools, { limit: 5 });
  return matches.map(m => m.tool.name);
}

args.skipStorage?

boolean

Skip all storage operations (conversation, messages, embeddings, media). Use this for one-off tasks like title generation where you don’t want to pollute the database with utility messages.

When true:

• No conversation is created or required
• Messages are not stored in the database
• No embeddings are generated
• No media/files are processed for storage
• Result will not include userMessage or assistantMessage

Default

false

Example

// Generate a title without storing anything
const { data } = await sendMessage({
  messages: [{ role: "user", content: [{ type: "text", text: "Generate a title for: ..." }] }],
  skipStorage: true,
  includeHistory: false,
});

args.sources?

SearchSource[]

Search sources to attach to the stored message for citation/reference. Note: Sources are also automatically extracted from tool_call_events in the response.

args.temperature?

number

Controls randomness in the response (0.0 to 2.0). Lower values make output more deterministic, higher values more creative.

args.thinking?

LlmapiThinkingOptions

Extended thinking configuration for Anthropic models (Claude). Enables the model to think through complex problems step by step before generating the final response.

args.thoughtProcess?

ActivityPhase[]

Activity phases for tracking the request lifecycle in the UI. Each phase represents a step like “Searching”, “Thinking”, “Generating”. The final phase is automatically marked as completed when stored.

Note: If you need activity phases that are added during streaming (e.g., server tool calls), use getThoughtProcess callback instead, which captures phases AFTER streaming completes.

args.toolChoice?

string

Controls which tool the model should use:

• “auto”: Model decides whether to use a tool (default)
• “any”: Model must use one of the provided tools
• “none”: Model cannot use any tools
• “required”: Model must use a tool
• Specific tool name: Model must use that specific tool

id

string | null

id

string

title

string