Client SDK · Chat

Chat.

Send messages and get complete responses from the chat API.

`chat.create(params, options?)`

Sends a chat message and returns the complete response. Internally this runs the stream and collects all events.

TypeScript

const response = await client.chat.create({
  input: 'What is the capital of Australia?',
  conversationId: 'conv-123',
  responseMode: 'instant',
});

console.log(response.outputText);
console.log(response.usage);

`ChatCreateParams`

Field	type	description
input	string	The user's message. Required if messages is not provided.
messages	ApiMessage[]	Explicit message array. Overrides input. Each message: { role: 'user' \| 'assistant', content: string }.
conversationId	string	Associates this message with a conversation thread for multi-turn chat.
fileIds	string[]	File IDs to attach (from files.upload()).
responseMode	ChatResponseMode	Response depth: 'auto', 'instant', or 'deep'. Defaults to 'auto'.
responseSchema	string	Raw JSON Schema (as a string) to grammar-constrain the response to. Prefer chat.streamObject / chat.createObject, which convert a zod schema for you (see Structured output).

`MatildaRequestOptions`

Extends RequestOptions. All fields optional.

Field	type	description
fingerprint	string \| null	Device fingerprint for rate limiting.
accessToken	string \| null	Override the client-level access token for this request.
signal	AbortSignal	Abort the request.
stallTimeoutMs	number	SSE stall watchdog timeout in ms. Defaults to 45_000. Pass 0 to disable.
onEvent	(event: MatildaChatStreamEvent) => void	Catch-all stream event hook — fires for every event. Only honoured by convenience methods that consume the stream for you (chat.create(), chat.createObject()); use chat.stream() when you want to process events yourself.

`MatildaChatResponse`

Field	type	description
outputText	string	The full assistant response text.
events	MatildaChatStreamEvent[]	Every event emitted during the stream.
streamId	string \| undefined	Durable stream ID (from stream_init event).
lastEventId	string \| undefined	Last Redis stream entry ID (for resume).
usage	UsageEvent \| undefined	Token usage data.
errors	Array<{ code: ChatErrorCode; message: string }>	Any errors emitted during the stream.
truncatedReason	string \| undefined	Why the response was truncated (e.g. 'max_tokens').

`ChatResponseMode`

TypeScript

type ChatResponseMode = 'auto' | 'instant' | 'deep';

'auto' — Server decides the optimal response depth.
'instant' — Optimised for low latency.
'deep' — Optimised for thoroughness.