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 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 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) 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

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

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

Data shape (--output 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

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

Data shape (--output 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

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

Data shape (--output 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

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

Data shape (--output 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

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)

{ "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

uip conversational trunks list --direction inbound

Data shape (--output json)

{
  "Result": "Success",
  "Code": "SipTrunkList",
  "Data": [
    { "id": "t1t2t3t4-0000-0000-0000-000000000001", "phoneNumber": "[phone]", "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. [phone]).

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

# Auto-resolve the entry point (release has exactly one Incoming call trigger)
uip conversational trunks assign [phone] --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 [phone] --clear -y

Data shape (--output json)

{
  "Result": "Success",
  "Code": "SipTrunkAssign",
  "Data": { "id": "t1t2t3t4-0000-0000-0000-000000000001", "phoneNumber": "[phone]", "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

uip conversational user-settings get

Data shape (--output json)

{
  "Result": "Success",
  "Code": "UserSettings",
  "Data": { "name": "Jane Doe", "email": "[e-mail]", "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

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

Data shape (--output json)

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

Related

• uip conversational — chat, agents, conversations.

See also

• Global options
• Exit codes