# Configure

Streaming\:Flux

## Introduction

Real conversations aren't static. A call that starts with casual confirmation ("Can you verify your name?") shifts to strict authentication ("Please say your 6-digit PIN") and then to open-ended troubleshooting. Conversations evolve through discrete sections, intents, and steps—each with different demands on your speech recognition system.

The `Configure` control message enables you to adapt Flux's behavior mid-stream as conversational context evolves, without disconnecting and reconnecting. This is essentially **context injection for speech recognition**: you inject the specific vocabulary, turn detection behavior, and timing parameters needed for each phase of the conversation.

### Why This Matters for Voice Agents

The ASR behavior you want at minute one isn't what you want at minute three. With dynamic configuration, you can:

**Dynamically bias toward task-critical phrases.** Collecting a customer's name? Add it to keyterms right before you ask. Moving from appointment scheduling to pharmacy? Swap in medication names and medical terminology. Handling a product inquiry? Load the specific product names and feature terminology relevant to that conversation. You're no longer stuck with a generic keyterm list that's "good enough" for the whole call or loading hundreds of irrelevant terms upfront.

**Adjust turn detection for critical flows.** When you're collecting a password, OTP, or account number, you don't want Flux cutting off the user mid-utterance. Increase `eot_timeout_ms` and `eot_threshold` values for that segment to allow longer pauses and wait for higher confidence before detecting turn end, then decrease them when you're back to natural conversation.

**Switch number formatting per step.** Turn on `numerals` right before you ask for a PIN, phone number, or order number so the transcript returns digits ("4 8 1 5"), then turn it off when the conversation returns to free-form speech.

**Reduce engineering complexity.** Without dynamic configuration, changing ASR behavior mid-call meant reconnecting (dropping audio, managing state transitions) or worse, managing multiple concurrent streams and swapping between them. That's a state machine you never wanted to build and definitely don't want to maintain. Configure gives you one connection with dynamic behavior.

Configuration updates are processed in order with your audio stream and take effect immediately when processed. The stream continues uninterrupted, and you receive confirmation of successful updates via `ConfigureSuccess` messages.

## Configurable Parameters

You can update the following parameters mid-stream:

| Parameter             | Type    | Range                    | Description                                                                                                                                                                                                                                                                        |
| --------------------- | ------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keyterms`            | array   | Up to 100 terms          | Custom vocabulary terms to boost recognition accuracy. **Note:** Sending keyterms replaces the entire list, not merge.                                                                                                                                                             |
| `language_hints`      | array   | Supported language codes | Bias `flux-general-multi` toward specific languages. **Note:** Non-empty array replaces current hints. Empty array `[]` clears hints. Omit or `null` to keep current hints unchanged. See [Language Prompting](/guides/streaming-audio-flux-language-prompting).                   |
| `eot_threshold`       | number  | 0.5-1.0                  | Confidence threshold for standard turn detection. Higher values mean more confidence required before detecting turn end. Set to `1.0` to suppress natural end-of-turn.                                                                                                             |
| `eager_eot_threshold` | number  | 0.3-0.9                  | Confidence threshold for eager turn detection. Must be ≤ `eot_threshold`.                                                                                                                                                                                                          |
| `eot_timeout_ms`      | number  | 500-60000                | Maximum silence duration (in milliseconds) before forcing turn end.                                                                                                                                                                                                                |
| `numerals`            | boolean | `true` / `false`         | Convert numbers from written format to numerical format (for example, "twenty twenty six" to "2026"). Applies to transcripts Flux STT sends after it processes the update. Set the initial value with the `numerals` query parameter. See [Numerals](/guides/formatting-numerals). |

All parameters are optional in a Configure message. Omitted parameters retain their current values.

> **keyterms are plain strings—no weights**
>
> Each entry in the `keyterms` array is a plain term or phrase. Like the query-string [`keyterm`](/guides/custom-vocabulary-keyterm) parameter, Flux keyterms do **not** support the weight/intensifier syntax from the legacy [Keywords](/guides/custom-vocabulary-keywords) feature. Do not append a weight such as `"term:0.15"`; pass a multi-word phrase as a single array element, for example `["customer service"]`.

## Message Structure

### Configure Message

Thresholds must be nested under a `"thresholds"` object. Individual threshold properties can be sent without including all three.

:::code-group
```json title="Update Thresholds Only"
{
  "type": "Configure",
  "thresholds": {
    "eot_threshold": 0.8,
    "eot_timeout_ms": 5000
  }
}
```

```json title="Update Keyterms Only"
{
  "type": "Configure",
  "keyterms": ["product_name", "feature_name", "company_name"]
}
```

```json title="Update Both"
{
  "type": "Configure",
  "thresholds": {
    "eager_eot_threshold": 0.4,
    "eot_threshold": 0.7,
    "eot_timeout_ms": 6000
  },
  "keyterms": ["apple", "banana", "orange"]
}
```

```json title="Clear All Keyterms"
{
  "type": "Configure",
  "keyterms": []
}
```

```json title="Update Language Hints (flux-general-multi)"
{
  "type": "Configure",
  "language_hints": ["en", "es", "fr"]
}
```

```json title="Update Language Hints and Thresholds"
{
  "type": "Configure",
  "language_hints": ["en", "es"],
  "thresholds": {
    "eot_threshold": 0.8,
    "eot_timeout_ms": 6000
  },
  "keyterms": ["product_name"]
}
```

```json title="Clear Language Hints (revert to auto-detect)"
{
  "type": "Configure",
  "language_hints": []
}
```

```json title="Update Numerals"
{
  "type": "Configure",
  "numerals": true
}
```
:::

### Response Messages

#### ConfigureSuccess

Returned when configuration update is successfully applied. Returns the full active configuration, including fields you didn't change.

```json
{
  "type": "ConfigureSuccess",
  "thresholds": {
    "eager_eot_threshold": 0.4,
    "eot_threshold": 0.7,
    "eot_timeout_ms": 6000
  },
  "keyterms": ["apple", "banana", "orange"],
  "language_hints": ["en", "es"],
  "profanity_filter": false,
  "redact_usage": false,
  "numerals": true
}
```

#### ConfigureFailure

Returned when configuration update fails validation. The stream continues with the previous configuration.

```json
{
  "type": "ConfigureFailure",
  "request_id": "01a0e80f-3782-7413-afc3-091fabadf0a8",
  "sequence_id": 1,
  "code": "UNPARSABLE_CLIENT_MESSAGE",
  "description": "eager_eot_threshold cannot be greater than eot_threshold."
}
```

## Important Behaviors

### Configuration Update Timing

Key timing behaviors:

- Updates apply immediately when the Configure message is processed
- Updates persist until the stream ends or another Configure message is sent
- Turn boundaries do not affect when updates take effect
- Already-transcribed audio is NOT reprocessed with new configuration

### Keyterm Overwrite Behavior

:::callout{intent="warning"}
**Critical:** When sending a Configure message with keyterms, the ENTIRE keyterms list is replaced, not merged. If you want to add terms, you must include both existing and new terms.
:::

Example:

```
Initial keyterms:    ["apple", "banana", "orange"]
Configure with:      {"keyterms": ["grape", "kiwi"]}
Result:              ["grape", "kiwi"]
                     // "apple", "banana", "orange" are REMOVED
```

To add terms while keeping existing ones, retrieve the current keyterms first (via application state tracking or the initial configuration), then send a Configure message with the combined list.

### Exclusion vs. Clearing

Different behaviors apply when you omit fields versus explicitly clearing them:

| Scenario                      | JSON Example                                    | Behavior                                  |
| ----------------------------- | ----------------------------------------------- | ----------------------------------------- |
| Omit keyterms                 | `{"type": "Configure", "thresholds": {...}}`    | No change to keyterms                     |
| Empty keyterms array          | `{"type": "Configure", "keyterms": []}`         | Clears all keyterms                       |
| Omit threshold property       | `{"thresholds": {"eot_threshold": 0.8}}`        | No change to other thresholds             |
| Omit entire thresholds object | `{"type": "Configure", "keyterms": [...]}`      | No change to any thresholds               |
| Omit language\_hints          | `{"type": "Configure", "keyterms": [...]}`      | No change to language hints               |
| Empty language\_hints array   | `{"type": "Configure", "language_hints": []}`   | Clears all hints (reverts to auto-detect) |
| Set language\_hints to null   | `{"type": "Configure", "language_hints": null}` | No change to language hints               |
| Omit numerals                 | `{"type": "Configure", "keyterms": [...]}`      | No change to numerals                     |
| Set numerals to null          | `{"type": "Configure", "numerals": null}`       | No change to numerals                     |

### Validation Rules

Configure messages are validated using the same rules as initial connection parameters:

- `eager_eot_threshold` must be ≤ `eot_threshold` (if both are specified in the message)
- Threshold values must be within valid ranges
- Keyterms array must contain ≤ 100 terms
- `numerals` must be a JSON boolean (`true` or `false`)

**Important:** A failed Configure message (returning `ConfigureFailure`) does NOT affect the stream. The connection continues with the previous configuration unchanged. Schema errors are the exception: a message that fails schema validation closes the connection (see the warning below).

Flux STT applies all fields in a Configure message together or not at all. If one field fails, such as an invalid `keyterms` list sent alongside `numerals`, none of the fields take effect.

:::callout{intent="warning"}
A Configure message that fails schema validation, such as `{"type": "Configure", "numerals": "true"}`, returns a message with `type: Error` and code `UNPARSABLE_CLIENT_MESSAGE`, and Flux STT closes the connection. `ConfigureFailure` can carry the same code, so check `type` to tell the two apart.
:::

## Related Resources

- [Configuration Parameters](/guides/streaming-audio-flux-configuration) - Complete reference for all Flux configuration options
- [Keyterm Boosting](/guides/custom-vocabulary-keyterm) - Detailed guide to using keyterms for custom vocabulary
- [State Messages](/guides/streaming-audio-flux-state) - Understanding turn detection and state transitions
- [Getting Started with Flux](/guides/streaming-audio-flux-quickstart) - Quickstart guide with basic configuration
- [Close Stream](/guides/streaming-audio-flux-close-stream) - Close the WebSocket stream
- [Force End Turn](/guides/streaming-audio-flux-force-end-turn) - End the current turn immediately from an external signal

***

## Related pages

- [Close Stream](./streaming-audio-flux-close-stream.md)
- [Force End Turn](./streaming-audio-flux-force-end-turn.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.