# Chat

> Send messages and get complete responses from the chat API.

Source: https://maincode.com/docs/client-sdk-chat
Section: Client SDK · Matilda documentation

---

## `chat.create(params, options?)`

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

```ts title="chat.ts"
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`

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

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