# Conversation

List, search, pin, rename, delete, and select your agent's conversations.

Manage a user's conversations with your agent: fetch and search them, pin the important ones, and rename, delete, or select a conversation by ID.

:::note[Prerequisites]
The [SDK is installed and initialized](/start/install/). Call these methods inside the `foldspace('when', 'ready', ...)` callback.
:::

## List conversations

### `getConversations(options)`

Fetch conversations with pagination, search, and filtering.

```javascript
foldspace.agent('AGENT_NAME').getConversations({
    pagination: { pageNumber: number, pageSize: number },
    search: { value: string },
    filters: { pinned: boolean }
});
```

| Parameter | Type | Description |
| --- | --- | --- |
| `pagination.pageNumber` | number | Page to fetch. |
| `pagination.pageSize` | number | Number of conversations per page. |
| `search.value` | string | Filter conversations by search term. |
| `filters.pinned` | boolean | When set, restrict results by pinned state. |

## Get a conversation name

### `getConversationName(conversationId)`

Get the name (title) of a conversation by ID.

```javascript
foldspace.agent('AGENT_NAME').getConversationName('CONVERSATION_ID');
```

## Pin and unpin conversations

### `pinConversation(conversationId)` / `unpinConversation(conversationId)`

Pin or unpin a conversation by ID.

```javascript
foldspace.agent('AGENT_NAME').pinConversation('CONVERSATION_ID');
foldspace.agent('AGENT_NAME').unpinConversation('CONVERSATION_ID');
```

## Rename and delete conversations

### `renameConversation(conversationId, name)` / `deleteConversation(conversationId)`

Rename or delete a conversation by ID.

```javascript
foldspace.agent('AGENT_NAME').deleteConversation('CONVERSATION_ID');
foldspace.agent('AGENT_NAME').renameConversation('CONVERSATION_ID', 'NEW_NAME');
```

## Select a conversation

### `selectConversation(conversationId)`

Make a conversation the active one by ID.

```javascript
foldspace.agent('AGENT_NAME').selectConversation('CONVERSATION_ID');
```

## Related

- [Messaging API](/reference/messaging-api/): send messages to your agent.
- [Agent Event API](/reference/agent-event-api/): react to `conversation.created` and other events.