# uip conversational exchanges, messages, trunks, user-settings

> Syntax and options for conversation history and feedback (exchanges, messages), voice-channel routing (trunks), and profile settings (user-settings) under `uip conversational`.

Part of the [`uip conversational`](./uip-conversational.md) tool. This page covers four command groups: **exchanges** and **messages** read a conversation's history and let you rate exchanges; **trunks** manages the SIP phone numbers a voice-enabled conversational agent answers or dials from; **user-settings** manages the current user's conversational profile. None of these create or drive a conversation — see the [parent page](./uip-conversational.md) for `chat`, `agents`, and `conversations`.

## Concepts

- **Exchange** — one request/response round-trip within a conversation: a user message in, an assistant message (with content parts, tool calls, citations) out. `chat` (on the [parent page](./uip-conversational.md#uip-conversational-chat)) drives exchanges live; this page's `exchanges`/`messages` verbs read them back afterward.
- **Message → content part** — a message is a container for one or more content parts (text/markdown chunks, tool-call records). `messages get-content-part` fetches one part directly; if the direct lookup fails, the CLI falls back to fetching the parent message and searching its `contentParts` array before giving up.
- **Trunk** — a SIP phone number connected in Instance Management under Phone numbers. Outbound-enabled trunks are dialed from by a voice flow's "Create outgoing call" activity; inbound-enabled trunks route incoming calls to a published Flow process release via `trunks assign`.

## Synopsis

```text
uip conversational exchanges list <conversation-id> [--limit <n>] [--exchange-sort <order>] [--message-sort <order>] [--cursor <token>]
uip conversational exchanges get <conversation-id> <exchange-id> [--message-sort <order>]
uip conversational exchanges feedback <conversation-id> <exchange-id> --rating positive|negative [--comment <text>]
uip conversational messages get <conversation-id> <exchange-id> <message-id>
uip conversational messages get-content-part <conversation-id> <exchange-id> <message-id> <content-part-id>
uip conversational trunks list [--direction inbound|outbound]
uip conversational trunks assign <trunk> [--process-key <key> --folder-key <key> [--entry-point <id>] | --clear] [-y]
uip conversational user-settings get
uip conversational user-settings update [--name <name>] [--email <email>] [--role <role>] [--department <department>] [--company <company>] [--country <country>] [--timezone <timezone>]
```

## uip conversational exchanges

Retrieve and give feedback on conversation exchanges.

### uip conversational exchanges list

#### Arguments

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

#### Options

| Long | Value | Description |
|---|---|---|
| `--limit <number>` | positive integer | Exchanges per page. |
| `--exchange-sort <order>` | `ascending`\|`descending` | Sort order for exchanges. |
| `--message-sort <order>` | `ascending`\|`descending` | Sort order for messages within each exchange. |
| `--cursor <token>` | string | Pagination cursor for the next page. |

#### Example

```bash
uip conversational exchanges list b2c3d4e5-0000-0000-0000-000000000001 --limit 20
```

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

```json
{
  "Result": "Success",
  "Code": "ExchangeList",
  "Data": {
    "items": [{ "id": "e1e2e3e4-0000-0000-0000-000000000001", "...": "raw exchange record" }],
    "nextCursor": null
  }
}
```

### uip conversational exchanges get

#### Arguments

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

#### Options

| Long | Value | Description |
|---|---|---|
| `--message-sort <order>` | `ascending`\|`descending` | Sort order for messages in the returned exchange. |

#### Example

```bash
uip conversational exchanges get b2c3d4e5-0000-0000-0000-000000000001 e1e2e3e4-0000-0000-0000-000000000001
```

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

```json
{ "Result": "Success", "Code": "Exchange", "Data": { "id": "e1e2e3e4-0000-0000-0000-000000000001", "messages": [] } }
```

### uip conversational exchanges feedback

#### Arguments

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

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--rating <rating>` | `positive`\|`negative` | **yes** | Feedback rating. Any other value fails client-side before any network call. |
| `--comment <comment>` | string | no | Optional feedback comment. |

#### Example

```bash
uip conversational exchanges feedback b2c3d4e5-0000-0000-0000-000000000001 e1e2e3e4-0000-0000-0000-000000000001 --rating positive --comment "Resolved quickly"
```

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

```json
{ "Result": "Success", "Code": "FeedbackCreated", "Data": { "rating": "positive", "comment": "Resolved quickly" } }
```

## uip conversational messages

Retrieve conversation messages and their content parts.

### uip conversational messages get

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |
| `<exchange-id>` | yes | Exchange UUID. |
| `<message-id>` | yes | Message UUID. |

#### Example

```bash
uip conversational messages get b2c3d4e5-0000-0000-0000-000000000001 e1e2e3e4-0000-0000-0000-000000000001 f1f2f3f4-0000-0000-0000-000000000001
```

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

```json
{ "Result": "Success", "Code": "Message", "Data": { "id": "f1f2f3f4-0000-0000-0000-000000000001", "contentParts": [] } }
```

### uip conversational messages get-content-part

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<conversation-id>` | yes | Conversation UUID. |
| `<exchange-id>` | yes | Exchange UUID. |
| `<message-id>` | yes | Message UUID. |
| `<content-part-id>` | yes | Content part UUID. |

If the direct content-part lookup fails, the CLI automatically retries by fetching the parent message and searching its `contentParts` array for a matching `id` or `contentPartId` before reporting an error.

#### Example

```bash
uip conversational messages get-content-part b2c3d4e5-0000-0000-0000-000000000001 e1e2e3e4-0000-0000-0000-000000000001 f1f2f3f4-0000-0000-0000-000000000001 a1a2a3a4-0000-0000-0000-000000000001
```

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

```json
{ "Result": "Success", "Code": "ContentPart", "Data": { "id": "a1a2a3a4-0000-0000-0000-000000000001", "isText": true, "data": "..." } }
```

## uip conversational trunks

Inspect and route the tenant's SIP trunks (phone numbers) configured for conversational voice.

### uip conversational trunks list

#### Options

| Long | Value | Description |
|---|---|---|
| `--direction <direction>` | `inbound`\|`outbound` | Only trunks enabled for this call direction. Omit to list every trunk. Any other value fails client-side. |

#### Example

```bash
uip conversational trunks list --direction inbound
```

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

```json
{
  "Result": "Success",
  "Code": "SipTrunkList",
  "Data": [
    { "id": "t1t2t3t4-0000-0000-0000-000000000001", "phoneNumber": "+18334815468", "inboundEnabled": true, "outboundEnabled": false, "processKey": null }
  ]
}
```

### uip conversational trunks assign

Route a trunk's inbound calls to a published Flow process release, or clear the routing with `--clear`. The process must be a deployed Flow release whose flow starts from an **Incoming call** trigger; when the flow has exactly one such trigger, `--entry-point` can be omitted and is resolved automatically — when it has more than one, `--entry-point` is required and the command fails listing the valid IDs.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<trunk>` | yes | Trunk ID (GUID) or its phone number in E.164 form (e.g. `+18334815468`). |

#### Options

| Long | Value | Description |
|---|---|---|
| `--process-key <key>` | GUID | Orchestrator release key of the deployed Flow process (`uip or processes list` shows it as `Key`). Required unless `--clear`. |
| `--folder-key <key>` | GUID | Key of the Orchestrator folder the release lives in. Required unless `--clear`. |
| `--entry-point <id>` | string | Incoming-call entry point ID inside the flow package. Resolved automatically when the flow has exactly one; required (and validated against the release's real entry points) otherwise. |
| `--clear` | flag | Remove the trunk's inbound process routing. Mutually exclusive with `--process-key`/`--folder-key`/`--entry-point` — combining them fails client-side. |
| `-y, --yes` | flag | Confirm re-routing or clearing a trunk that already has inbound routing. Required in that case — the CLI never prompts. |

Validation order: `--clear` vs. the process/folder pair is checked first; then the trunk must actually be `inboundEnabled` (a routing attempt on an outbound-only trunk fails, pointing at `trunks list --direction inbound`); then, if the trunk already has a binding, `-y` is required; then the release's real Incoming-call entry points are listed from the platform and validated against `--entry-point` (or auto-resolved) before the binding is written — the write is all-or-nothing.

#### Examples

```bash
# Auto-resolve the entry point (release has exactly one Incoming call trigger)
uip conversational trunks assign +18334815468 --process-key 9e4b2f17-7c3a-4d81-b592-3f6e8a1d5c09 --folder-key a9f3b2c1-7d4e-4a8b-9c2f-5e1d3b6a8f7e

# Clear inbound routing on a bound trunk
uip conversational trunks assign +18334815468 --clear -y
```

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

```json
{
  "Result": "Success",
  "Code": "SipTrunkAssign",
  "Data": { "id": "t1t2t3t4-0000-0000-0000-000000000001", "phoneNumber": "+18334815468", "processKey": "9e4b2f17-7c3a-4d81-b592-3f6e8a1d5c09", "folderKey": "a9f3b2c1-7d4e-4a8b-9c2f-5e1d3b6a8f7e", "entryPoint": "..." }
}
```

`--clear` writes `{ processKey: null, folderKey: null, entryPoint: null }`.

## uip conversational user-settings

Manage the current user's conversational profile settings.

### uip conversational user-settings get

No options beyond globals.

#### Example

```bash
uip conversational user-settings get
```

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

```json
{
  "Result": "Success",
  "Code": "UserSettings",
  "Data": { "name": "Jane Doe", "email": "jane@example.com", "role": "Support Lead", "department": "Support", "company": "Acme", "country": "US", "timezone": "America/New_York" }
}
```

### uip conversational user-settings update

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

#### Options

| Long | Value | Description |
|---|---|---|
| `--name <name>` | string | User name. |
| `--email <email>` | string | Email address. |
| `--role <role>` | string | User role. |
| `--department <department>` | string | Department. |
| `--company <company>` | string | Company. |
| `--country <country>` | string | Country. |
| `--timezone <timezone>` | string | Timezone. |

#### Example

```bash
uip conversational user-settings update --timezone "America/Los_Angeles"
```

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

Same shape as `get`'s response, `Code: "UserSettingsUpdated"`.

## Related

- [`uip conversational`](./uip-conversational.md) — `chat`, `agents`, `conversations`.

## See also

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