# Conversations

> List, retrieve, rename, and rate the threads behind a conversationId.

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

---

## `conversations.list(options?)`

Lists conversations with pagination.

```ts title="list.ts"
const result = await client.conversations.list({ limit: 20, offset: 0 });
for (const conv of result.conversations) {
  console.log(`${conv.id}: ${conv.title} (updated ${conv.updatedAt})`);
}
```

| Field | Type | Description |
| - | - | - |
| `limit` | `number` | Maximum number of conversations to return. |
| `offset` | `number` | Pagination offset. |
| `fingerprint` | `string \| null` | Device fingerprint. |
| `accessToken` | `string \| null` | Override access token. |

Returns `Promise<ConversationListResponse>`:

```ts
interface ConversationListResponse {
  conversations: ConversationSummary[];
  total: number;
  limit: number;
  offset: number;
}

interface ConversationSummary {
  id: string;
  userId: string;
  title: string;
  createdAt: string;
  updatedAt: string;
}
```

## `conversations.retrieve(conversationId, options?)`

Retrieves a full conversation thread with all messages.

```ts title="retrieve.ts"
const conv = await client.conversations.retrieve('conv-123');
for (const msg of conv.messages) {
  console.log(`[${msg.role}] ${msg.content}`);
}
```

Returns `Promise<ConversationRecord>`:

```ts
interface ConversationRecord extends ConversationSummary {
  messages: ConversationMessage[];
}

interface ConversationMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  feedback?: 'positive' | 'negative' | null;
  attachments?: FileAttachment[];
  tokensUsed?: number | null;
  parentId?: string | null;
  generationOrdinal?: number;
  status?: 'completed' | 'failed' | 'interrupted';
  errorCode?: string | null;
  createdAt: string;
}
```

## `conversations.update(conversationId, patch, options?)`

Updates a conversation's metadata (currently only title).

```ts
await client.conversations.update('conv-123', { title: 'My Chat About AI' });
```

| Field | Type | Description |
| - | - | - |
| `conversationId` | `string` | The conversation to update. |
| `patch` | `{ title?: string }` | Fields to update. |

Returns `Promise<void>`.

## `conversations.setMessageFeedback(conversationId, messageId, feedback, options?)`

Sets thumbs-up or thumbs-down feedback on a specific message.

```ts
await client.conversations.setMessageFeedback('conv-123', 'msg-456', 'positive');
```

| Field | Type | Description |
| - | - | - |
| `conversationId` | `string` | The conversation containing the message. |
| `messageId` | `string` | The message to rate. |
| `feedback` | `'positive' \| 'negative'` | The feedback value. |

Returns `Promise<{ ok: boolean }>`.