# uip conversational

> Syntax and options for `uip conversational`, which chats with deployed UiPath conversational agents and manages the conversations that result — chat, agents, and conversations.

`uip conversational` interacts with deployed **conversational agents** — Orchestrator-deployed processes exposed as a chat interface, built on the UiPath conversational-agent runtime. This page covers discovering agent releases (`agents`), starting/managing the conversations you have with them (`conversations`), and chatting in real time (`chat`). For conversation history, feedback, voice-channel routing, and profile settings, see [Conversational: exchanges, messages, trunks & user-settings](./uip-conversational-history.md).

## Concepts

- **Agent release** — a deployed Orchestrator process release that has conversational capability enabled, identified by a release ID plus the folder it lives in. Discover releases with [`agents list`](#uip-conversational-agents-list).
- **Conversation** — a persistent session against one agent release, created with [`conversations create`](#uip-conversational-conversations), identified by a UUID. All chat activity happens inside a conversation.
- **Chat vs. conversations** — `conversations create`/`list`/`get` manage the conversation record itself (metadata, label, agent input); `chat` is the live, real-time interaction with an *existing* conversation — you create a conversation first, then `chat` into it.
- **`--agent-input`** on `conversations create`/`update` is a JSON string that seeds or updates the agent's initial input for the conversation; it's wrapped as `{ inline: <parsed JSON> }` before being sent.

## Synopsis

```text
uip conversational chat <conversation-id> [-m, --message <text>]
uip conversational agents list [--folder-id <id>]
uip conversational agents get --release-id <id> --folder-id <id>
uip conversational conversations create --release-id <id> --folder-id <id> [--label <label>] [--autogenerate-label | --no-autogenerate-label] [--agent-input <json>]
uip conversational conversations list [--limit <n>] [--sort-order <order>] [--cursor <token>] [--agent-id <id>] [--agent-key <guid>] [--label <substring>]
uip conversational conversations get <conversation-id>
uip conversational conversations update <conversation-id> [--label <label>] [--autogenerate-label | --no-autogenerate-label] [--agent-input <json>]
uip conversational conversations delete <conversation-id> -y
uip conversational conversations attachments upload <conversation-id> --file <path>
uip conversational conversations attachments get-uri <conversation-id> --file-name <name>
```

## uip conversational chat

Interact with an existing conversation in real time — either a single-shot message (`--message`) or an interactive REPL (omit `--message`).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID (from `conversations create`/`list`). |

### Options

| Long | Value | Description |
|---|---|---|
| `-m, --message <text>` | string | Send a single message and exit after the exchange completes (non-interactive). Omit to start the interactive REPL instead. |

Without `--message`, `chat` requires a prompt-capable terminal — it fails fast in a non-interactive environment (CI, piped output) with instructions to use `--message` instead. In the REPL, type `/exit` or `/quit` to end the session, or press Ctrl+C. Assistant responses stream to stdout token-by-token; inline citation markers (`[1]`, `[2]`, ...) render as the response streams, and a `--- Citations ---` footnote block with titles/URLs prints after each exchange completes, deduplicated across the session.

### Examples

```bash
# Single-shot message
uip conversational chat b2c3d4e5-0000-0000-0000-000000000001 --message "What's the status of order 4471?"

# Interactive REPL
uip conversational chat b2c3d4e5-0000-0000-0000-000000000001
```

This command streams human-readable text to stdout rather than emitting the CLI's usual `--output json` envelope — it's designed for interactive use, not scripting. A start-up or mid-session error is still reported through the standard `OutputFormatter.error` envelope before the process exits non-zero.

## uip conversational agents

Inspect conversational agent releases.

### uip conversational agents list

#### Options

| Long | Value | Description |
|---|---|---|
| `--folder-id <id>` | positive integer | Filter conversational agents by folder. |

#### Example

```bash
uip conversational agents list --folder-id 123456
```

#### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConversationalAgentList",
  "Data": [
    {
      "id": 42,
      "releaseKey": "b2c3d4e5-0000-0000-0000-000000000001",
      "name": "Support Assistant",
      "description": "Handles tier-1 support conversations",
      "processVersion": "1.0.0",
      "processKey": "SupportAssistant",
      "folderId": 123456,
      "feedId": "c3d4e5f6-0000-0000-0000-000000000001",
      "createdTime": "2026-08-01T10:00:00Z"
    }
  ]
}
```

Keys are kept in native camelCase (`preserveDataKeys: true`), not PascalCased.

### uip conversational agents get

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--release-id <id>` | positive integer | **yes** | Agent release ID. |
| `--folder-id <id>` | positive integer | **yes** | Folder ID containing the agent. |

#### Example

```bash
uip conversational agents get --release-id 42 --folder-id 123456
```

#### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConversationalAgent",
  "Data": {
    "id": 42,
    "releaseKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "name": "Support Assistant",
    "description": "Handles tier-1 support conversations",
    "processVersion": "1.0.0",
    "processKey": "SupportAssistant",
    "folderId": 123456,
    "feedId": "c3d4e5f6-0000-0000-0000-000000000001",
    "createdTime": "2026-08-01T10:00:00Z",
    "appearance": { "...": "agent chat-widget appearance config" }
  }
}
```

`appearance` is the one field `get` returns beyond what `list` already shows.

## uip conversational conversations

Create, list, inspect, update, and delete conversations, plus manage their file attachments.

### uip conversational conversations create

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--release-id <id>` | positive integer | **yes** | ID of a conversational-enabled release. |
| `--folder-id <id>` | positive integer | **yes** | Folder ID containing the release. |
| `--label <label>` | string | no | Conversation label. |
| `--autogenerate-label` | flag | no | Enable label autogeneration after exchanges occur. |
| `--no-autogenerate-label` | flag | no | Disable label autogeneration. |
| `--agent-input <json>` | JSON string | no | Initial input for the agent — parsed and wrapped as `{ inline: <value> }`. Fails fast on invalid JSON. |

#### Example

```bash
uip conversational conversations create --release-id 42 --folder-id 123456 --label "Order 4471"
```

#### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConversationCreated",
  "Data": {
    "id": "b2c3d4e5-0000-0000-0000-000000000001",
    "label": "Order 4471",
    "autogenerateLabel": false,
    "agentId": 42,
    "folderId": 123456,
    "agentInput": { "inline": {} },
    "traceId": "d4e5f6a7-0000-0000-0000-000000000001",
    "spanId": "e5f6a7b8",
    "createdTime": "2026-08-01T10:00:00Z",
    "lastActivityTime": "2026-08-01T10:00:00Z"
  }
}
```

### uip conversational conversations list

#### Options

| Long | Value | Description |
|---|---|---|
| `--limit <number>` | positive integer | Conversations per page. |
| `--sort-order <order>` | `ascending`\|`descending` | Sort order. |
| `--cursor <token>` | string | Pagination cursor for the next page. |
| `--agent-id <id>` | positive integer | Filter by agent release ID. |
| `--agent-key <guid>` | string | Filter by agent release key. |
| `--label <substring>` | string | Filter by label substring, case-insensitive, 1-100 chars. |

#### Example

```bash
uip conversational conversations list --agent-id 42 --limit 20
```

#### Data shape (--output json)

```json
{
  "Result": "Success",
  "Code": "ConversationList",
  "Data": {
    "items": [{ "id": "b2c3d4e5-0000-0000-0000-000000000001", "label": "Order 4471" }],
    "nextCursor": null
  }
}
```

### uip conversational conversations get

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |

#### Example

```bash
uip conversational conversations get b2c3d4e5-0000-0000-0000-000000000001
```

#### Data shape (--output json)

Same shape as `create`'s response, `Code: "Conversation"`.

### uip conversational conversations update

At least one option is required — omitting all four fails client-side before any network call.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |

#### Options

| Long | Value | Description |
|---|---|---|
| `--label <label>` | string | New conversation label. |
| `--autogenerate-label` | flag | Enable label autogeneration. |
| `--no-autogenerate-label` | flag | Disable label autogeneration. |
| `--agent-input <json>` | JSON string | Updated agent input — replaces the whole value, wrapped as `{ inline: <value> }`. |

#### Example

```bash
uip conversational conversations update b2c3d4e5-0000-0000-0000-000000000001 --label "Order 4471 (resolved)"
```

#### Data shape (--output json)

Same shape as `create`'s response, `Code: "ConversationUpdated"`.

### uip conversational conversations delete

Destructive — requires `-y`/`--yes`; the CLI never prompts.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |

#### Options

| Long | Description |
|---|---|
| `-y, --yes` | Confirm this irreversible operation. Required — omitting it fails before any network call. |

#### Example

```bash
uip conversational conversations delete b2c3d4e5-0000-0000-0000-000000000001 -y
```

#### Data shape (--output json)

Same shape as `create`'s response, `Code: "ConversationDeleted"` — the deleted conversation's last known state.

### uip conversational conversations attachments upload

Upload a local file as a conversation attachment.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <path>` | path | **yes** | Path to the local file to upload. |

#### Example

```bash
uip conversational conversations attachments upload b2c3d4e5-0000-0000-0000-000000000001 --file ./invoice.pdf
```

#### Data shape (--output json)

```json
{ "Result": "Success", "Code": "AttachmentUploaded", "Data": { "...": "raw upload result from the conversational-agent SDK" } }
```

### uip conversational conversations attachments get-uri

Get a pre-signed upload URI for an attachment, without uploading a local file (for out-of-band uploads).

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file-name <name>` | string | **yes** | Name of the file the URI will accept. |

#### Example

```bash
uip conversational conversations attachments get-uri b2c3d4e5-0000-0000-0000-000000000001 --file-name invoice.pdf
```

#### Data shape (--output json)

```json
{ "Result": "Success", "Code": "AttachmentUri", "Data": { "...": "pre-signed URI payload" } }
```

## Related

- [Conversational: exchanges, messages, trunks & user-settings](./uip-conversational-history.md) — conversation history, feedback, voice-channel routing, and profile settings.

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)