Configuration

This guide assumes you have completed the Get started steps. Here you will find configuration options and API details for Feedback Agent.

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


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:


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:


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:


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

Was this page helpful?

Configuration​

FeedbackAgentEndpoint​

Session and lifecycle​

ASR states​

Submitting voice feedback​

Quick reference​