# Chat

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

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

---

## `chat.create(...)`

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

```python title="chat.py"
async def main():
    async with MatildaClient(token="...") as client:
        response = await client.chat.create(
            input="What is the capital of Australia?",
            conversation_id="conv-123",
            response_mode="instant",
        )

        print(response.output_text)
        print(response.usage)
```

### Parameters

| Field | Type | Description |
| - | - | - |
| `input` | `str \| None` | The user's message. Required if messages is not provided. |
| `messages` | `list[dict] \| None` | Explicit message array. Overrides input. Each message: { role: 'user' \| 'assistant', content: str }. |
| `conversation_id` | `str \| None` | Associates this message with a conversation thread for multi-turn chat. |
| `file_ids` | `list[str] \| None` | File IDs to attach (from files.upload()). |
| `response_mode` | `str \| None` | Response depth: 'auto', 'instant', or 'deep'. Defaults to 'auto'. |
| `response_schema` | `str \| None` | Raw JSON Schema (as a string) to grammar-constrain the response to. Prefer chat.stream\_object / chat.create\_object, which convert a pydantic model for you (see Structured output). |
| `access_token` | `str \| None` | Override the client-level access token for this request. |
| `fingerprint` | `str \| None` | Device fingerprint for rate limiting. |
| `stall_timeout_ms` | `int \| None` | SSE stall watchdog timeout in ms. Defaults to 45\_000. Pass 0 to disable. |
| `on_event` | `Callable[[ChatEvent], None] \| None` | Catch-all stream event hook — fires for every event. Only honoured by convenience methods that consume the stream for you (chat.create(), chat.create\_object()); use chat.stream() when you want to process events yourself. |

### `MatildaChatResponse`

| Field | Type | Description |
| - | - | - |
| `output_text` | `str` | The full assistant response text. |
| `events` | `list[ChatEvent]` | Every event emitted during the stream. |
| `stream_id` | `str \| None` | Durable stream ID (from the response.created event). |
| `last_event_id` | `str \| None` | Last Redis stream entry ID (for resume). |
| `usage` | `Usage \| None` | Token usage data. |
| `errors` | `list[StreamErrorInfo]` | Any errors emitted during the stream. |
| `truncated_reason` | `str \| None` | Why the response was truncated (e.g. 'max\_tokens'). |

### Response modes

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