Settings

Settings control how the assistant behaves in a conversation: its language, whether it is optimized for text or speech, whether it emits structured UI, and which handoff detectors are active.

Effective settings

ConversationSettings is the server's view — every field is always present in responses.

Field	Type	Default	Description
`language`	string	`"en"`	BCP-47 language tag.
`channel`	`"text"` or `"voice"`	`"text"`	Response mode optimized for text or for text-to-speech.
`ui_widgets_enabled`	boolean	`false`	Emit UI widgets in assistant content parts and as transient streaming events.
`opening_message_enabled`	boolean	`false`	Emit an opening assistant message automatically.
`risk_factors_enabled`	boolean	`true`	Allow the assistant to collect risk-factor evidence.
`geographic_risk_factors_enabled`	boolean	`false`	Allow the assistant to collect geographic risk-factor evidence.
`handoff_policies`	`HandoffPolicy[]`	`[]`	Enabled handoff detectors. An empty list disables handoff detection.
`max_message_length`	integer	`1500`	Maximum accepted length of a user message, counted in Unicode code points. Server-owned — see below.

Setting values

ConversationSettingsInput is the write model, used both when creating a conversation and when updating one. Every field is optional.

JSON

{
  "language": "pl",
  "channel": "voice",
  "ui_widgets_enabled": true,
  "handoff_policies": ["stop_intent_handoff"]
}

max_message_length is not accepted on input: it is configured per instance and reported back to you so the client can validate message length before sending. A message that exceeds it is rejected with message_too_long — 413 on HTTP, or an error event on WebSocket, where the socket stays open.

The limit counts Unicode code points, and it is measured on the text you send, before PII redaction. Redaction changes the length but never the verdict. Mind the unit when validating client-side: JavaScript's String.length counts UTF-16 units, so an emoji outside the Basic Multilingual Plane counts as 2 there and 1 here. Use [...text].length or Array.from(text).length to match the server.

On create

An omitted field falls back to the default configured for your instance, and then to the platform default from the table above. An explicit value always wins.

On update

PATCH /conversations/{conversation_id}/settings (or the WebSocket conversation.settings.update event) is a partial update — omitted fields keep their current value. The response carries the full effective settings after the merge.

cURL

curl "https://api.infermedica.com/api/ct/v2/conversations/68d9a84d-711c-4a55-a9dd-da6363e58e38/settings" \
  -X "PATCH" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "language": "pl", "channel": "voice" }'

ℹ️

A conversation keeps the settings resolved when it was created. Changing the defaults configured for your instance does not affect conversations already in flight.

Choosing a channel

channel changes how the assistant writes, not what it asks. voice produces copy meant to be spoken — shorter sentences, no visual formatting — and pairs with the interruption fields on user messages (is_interrupted, played_content). Use text for chat surfaces.

Conversation model Errors and rate limits