> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/v2/llms.txt)

# Configuration

This guide assumes you have completed the [Get started](https://docs.mapbox.com/android/navigation/v2/guides/get-started) steps. Here you will find configuration options and API details for Feedback Agent.

## Configuration

Feedback Agent is configured through `FeedbackAgentOptions`. Without additional configuration, the agent uses default values that work for most applications. Create options via the builder factory:

```
val options = FeedbackAgentOptions.Builder()
    .language(Locale.getDefault())
    .endpoint(FeedbackAgentEndpoint.Production)
    .build()
```

-   **`locale`** — The language used for user input (Automatic Speech Recognition). Defaults to `Locale.getDefault()`.
-   **`endpoint`** — The environment to use. Defaults to `FeedbackAgentEndpoint.Production`. See [FeedbackAgentEndpoint](#feedbackagentendpoint) below.

### FeedbackAgentEndpoint

The endpoint defines the WebSocket used for streaming and for Automatic Speech Recognition (ASR).

-   **`FeedbackAgentEndpoint.Production`** — Standard production endpoints. Use for released applications.

For self-hosted or custom backend, use a custom endpoint:

```kotlin
FeedbackAgentEndpoint.custom(
    name: String,
    streamingApiHost: String,
    streamingAsrApiHost: String
)
```

## Session and lifecycle

The entry point for Feedback Agent is `FeedbackAgentSession`. Register it with `MapboxNavigation` so the agent can take part in the navigation lifecycle:

```kotlin
val feedbackAgent = FeedbackAgentSession.Builder()
    .options(FeedbackAgentOptions.Builder().build())
    .build()
mapboxNavigation.registerObserver(feedbackAgent)
```

Session methods:

-   **`connect()`** — Starts a new session and establishes the WebSocket connection.
-   **`disconnect()`** — Closes the current session.
-   **`startListening()`** — Begins listening for user speech.
-   **`stopListening()`** — Stops listening and finalizes recognition.
-   **`interruptListening()`** — Terminates the ongoing conversation and ignores the last input.

## ASR states

`FeedbackAgentSession.asrState` is a `StateFlow<ASRState>` you can use for reactive UI binding. Handle each state in a `when` expression:

| State | Description |
| --- | --- |
| `ASRState.Idle` | ASR is connected and idle; not listening. |
| `ASRState.Listening(text)` | Now listening; `text` is the live transcription. |
| `ASRState.SpeechFinishedWaitingForResult` | User finished speaking; waiting for the backend result. |
| `ASRState.Result(text, feedbackType)` | Final result; use with `postVoiceFeedback`. |
| `ASRState.NoResult` | No recognizable speech detected. |
| `ASRState.Error(error)` | Recognition error. |
| `ASRState.Interrupted` | Recognition interrupted (for example, by lifecycle). |
| `ASRState.InterruptedByTimeout` | Timeout (no speech or no backend response). |

Example: when you receive `ASRState.Result`, submit the feedback and update your UI for other states:

```kotlin
feedbackAgent.asrState.collect { state ->
    when (state) {
        is ASRState.Listening -> updateTranscript(state.text)
        is ASRState.Result -> {
            mapboxNavigation.postVoiceFeedback(
                feedbackSubType = state.feedbackType,
                description = state.text,
                screenshot = encodedScreenshot,
                userFeedbackCallback = { /* handle completion */ }
            )
        }
        is ASRState.Error -> showError(state.error)
        else -> { }
    }
}
```

## Submitting voice feedback

Use the `postVoiceFeedback` extension on `MapboxNavigation` to send voice feedback to telemetry. Call it after `ASRState.Result`:

```kotlin
mapboxNavigation.postVoiceFeedback(
    feedbackSubType: String,
    description: String,
    screenshot: String,
    feedbackMetadata: FeedbackMetadata? = null,
    userFeedbackCallback: UserFeedbackCallback
)
```

-   **`feedbackSubType`** — Feedback subtype (for example from `FeedbackEvent.SubType`) or a custom string. When using ASR result, use `ASRState.Result.feedbackType`.
-   **`description`** — Description message. When using ASR result, use `ASRState.Result.text`.
-   **`screenshot`** — Encoded screenshot; use `FeedbackHelper.encodeScreenshot` and `ViewUtils.capture`.
-   **`feedbackMetadata`** — Optional. Attach feedback to a past location or time. See `MapboxNavigation.provideFeedbackMetadataWrapper`.
-   **`userFeedbackCallback`** — Invoked when the feedback has been processed.

You can call `postVoiceFeedback` outside an active trip until `MapboxNavigation.onDestroy`. When you provide `FeedbackMetadata`, the feedback is tied to the given location and time.

## Quick reference

| Component | Option | Type | Default |
| --- | --- | --- | --- |
| **FeedbackAgentOptions** | `language` | `Locale` | `Locale.getDefault()` |
| **FeedbackAgentOptions** | `endpoint` | `FeedbackAgentEndpoint` | `FeedbackAgentEndpoint.Production` |
| **FeedbackAgentSession** | `options` | `FeedbackAgentOptions` | `FeedbackAgentOptions.Builder().build()` |