Events

Ready to get started?

Create a free account to start building with Mapbox.

Sign Up

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Events are a way to be informed of the actions taken by the assistant as requested by user prompts. When the user has prompted the assistant to do something, the AI will trigger an action and respond with an event. For example, you can ask the assistant to play music, or to stop the navigation, and more advanced cases like changing the temperature in the car. Mapbox continues to build out more events and refine the existing ones.

There are several MapGPT events that can be observed with the SDK using the API observeMapGptEvents:

Body

Defines the event specifics, which varies based on the event type. All events mentioned below are extension of [Body] and inherit it's properties.

Properties	Type	Description
id	long	A unique increasing ID field for the event. This can be used by the client to reference the last received event ID when reconnecting to the service.
timestamp	long	Creation type of the event as unix timestamp.
chunkId	string	Describes which conversational chunk the event is tied to, in format of {date}@{id} where the chunkPrefix should be considered as an ID of the AI response and chunkOffset is the logical order in the response stream.
chunkPrefix	string	Represents an ID of the AI response.
chunkOffset	string	Represents logical order in the response stream.
isSupplement	boolean	Defines events that were not generated in direct response to user query but retroactively or spontaneously by the assistant.

Conversation

Defines a conversation chunk. A single chunk is typically a sentence in a longer AI response.

Properties	Type	Description
data	object	Contents related to conversation events.
data.conversationId	string	A unique string for this conversation.
data.content	string	The sentence in a response.
data.initial	boolean	Whether this is the first chunk in the response stream.
data.confirmation	boolean	Whether this chunk is a confirmation of a user action.
data.final	boolean	Whether this is the last chunk in the response stream.
data.maxTokens	boolean	Whether conversation has hit the profile's response token limit.

Entity

Defines entities, such as POIs or song names, extracted from a conversation or otherwise generated using this format.

Properties	Type	Description
data	array	List of contents related to entities.
data.place	object	Defines a POI entity.
data.place.name	string	An identified name of the entity such as restaurant name.
data.place.geocoded	object	Reverse geocoded place information.
data.card	object	Defines a card entity.
data.card.components	array	List of CardComponent.
data.card.anchoredComponent	object	CardComponent of the type CardComponent.Image describing the light and dark uri for the data provider if applicable.
data.card.payload	object	Additional payload associated with the card that is associated as a callback upon interaction.

PlayMusic

Defines an event to play a music.

Properties	Type	Description
data	object	Contents related to play music event.
data.provider	string	Provider specific uri of the track to be played.
data.uri	string	Contents related to play music event.
data.song	string	Name of the song.
data.artist	string	Name of the artist.

PauseMusic

Defines an event to pause music that is now playing.

ResumeMusic

Defines an event to resume music that was paused before.

StartNavigation

Defines an event to start navigation to a destination. The destination can be a POI name or a favorite such as "home" or "work".

Properties	Type	Description
data	object	Contents related to start navigation event.
data.location	string	Name of the place.
data.geocoded	string	Reverse geocoded place information.
data.favorite	string	Key to identify the location if it is a favorite.

To issue commands such as "Navigate me to home" or "Navigate me to work", you need to mention them as capabilities along with the query.

// Create a navigate to home capability middleware

class NavigateToHomeMiddleware:
    MapGptCapabilitiesMiddleware<NavigateToHomeMiddleware.NavigateToHomeContext>,
    CoroutineMiddleware<NavigateToHomeMiddleware.NavigateToHomeContext>() {

    inner class NavigateToHomeContext(mapGptCoreContext: MapGptCoreContext): MapGptCoreContext by mapGptCoreContext

    override fun <Parent : MiddlewareContext> provideContext(parent: Parent): NavigateToHomeContext {
        return NavigateToHomeContext(mapGptCoreContext = parent as MapGptCoreContext)
    }

    private val _capabilities = MutableStateFlow(setOf(NavigateToFavoriteCapability("home")))
    override val capabilities: Flow<Set<MapGptCapability>> = _capabilities.asStateFlow()

    override fun onAttached(middlewareContext: NavigateToHomeContext) {
        super.onAttached(middlewareContext)
        SharedLog.d(TAG) { "onAttached" }
    }

    override fun onDetached(middlewareContext: NavigateToHomeContext) {
        super.onDetached(middlewareContext)
        SharedLog.d(TAG) { "onDetached" }
    }

    private companion object {
        private const val TAG = "NavigateToHomeMiddleware"
    }
}

// Create a navigate to work capability middleware

class NavigateToWorkMiddleware:
    MapGptCapabilitiesMiddleware<NavigateToWorkMiddleware.NavigateToWorkContext>,
    CoroutineMiddleware<NavigateToWorkMiddleware.NavigateToWorkContext>() {

    inner class NavigateToWorkContext(mapGptCoreContext: MapGptCoreContext): MapGptCoreContext by mapGptCoreContext

    override fun <Parent : MiddlewareContext> provideContext(parent: Parent): NavigateToWorkContext {
        return NavigateToWorkContext(mapGptCoreContext = parent as MapGptCoreContext)
    }

    private val _capabilities = MutableStateFlow(setOf(NavigateToFavoriteCapability("work")))
    override val capabilities: Flow<Set<MapGptCapability>> = _capabilities.asStateFlow()

    override fun onAttached(middlewareContext: NavigateToWorkContext) {
        super.onAttached(middlewareContext)
        SharedLog.d(TAG) { "onAttached" }
    }

    override fun onDetached(middlewareContext: NavigateToWorkContext) {
        super.onDetached(middlewareContext)
        SharedLog.d(TAG) { "onDetached" }
    }

    private companion object {
        private const val TAG = "NavigateToWorkMiddleware"
    }
}

// Pass this to `capabilitiesRepository`

private val capabilitiesRepository = MapGptServiceCapabilitiesRepository(
    mapGptCore = mapGptCore,
    capabilityProvider = MapGptCapabilitiesProvider(
        scope = viewModelScope,
        capabilitiesServices = setOf(NavigateToHomeMiddleware(), NavigateToWorkMiddleware())
    ),
)

// Send the capability with the user request

val request = MapGptStreamingRequest(
    prompt = prompt,
    context = userContext,
    capabilities = capabilitiesRepository.capabilityIds(),
)
mapGptService.postPromptsForStreaming(request)

AddWaypoint

Defines an event to add a waypoint to an existing route.

Properties	Type	Description
data	object	Contents related to waypoint event.
data.index	integer	Index at which the waypoint should be added to the route.
data.location	string	Name of the place.
data.geocoded	string	Reverse geocoded place information.

UpdateCameraTracking

Defines an event to change the camera view as requested. The view can be follow the user, overview of the route, follow north up, tracking the puck.

Properties	Type	Description
data	object	Contents related to camera tracking event.
data.cameraTracking	object	Type of camera tracking event. Possible values include RECENTER, TRACKING_PUCK, TRACKING_NORTH, ROUTE_OVERVIEW, UNKNOWN

UpdateMapStyle

Defines an event to switch the map and user interface lighting and theme.

Properties	Type	Description
data	object	Contents related to style event.
data.theme	object	Type of map theme. Possible values include DEFAULT, FADED, MONO, UNKNOWN
data.lighting	object	Type of map lighting. Possible values include AUTO, DAY, DARK, DAWN, DUSK, UNKNOWN

StopNavigation

Defines an event to stop navigation.

NoResponse

Defines action containing no verbal response for the user query.

StopListening

Defines action ordering MapGPT to close the microphone and stop capturing input.

Observing events

See the Events API guide for more information on how to observe other events offered by the SDK. There are many data points to observe while navigating to a destination.

observeMapGptEvents

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                Dash.controller.observeMapGptEvents()
                    .collect { /* DashMapGptEvent */ event ->
                        // Do something with the MapGptEvent
                        processMapGptEvents(event)
                    }
            }
        }
    }

    fun processMapGptEvents(event: DashMapGptEvent) {
        when (event) {
            is DashMapGptEvent.Activated ->
                Toast.makeText(
                    this,
                    "New conversation with the assistant has started",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.PlayingMusic ->
                Toast.makeText(
                    this,
                    "App is playing the song with track identified by ${event.trackId}",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.PausedMusic ->
                Toast.makeText(
                    this,
                    "App has paused the music that was playing",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.ResumedMusic ->
                Toast.makeText(
                    this,
                    "App has resumed the music that was paused",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.StartedNavigation ->
                Toast.makeText(
                    this,
                    "App has started navigation to your destination",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.StoppedNavigation ->
                Toast.makeText(
                    this,
                    "App has stopped navigation",
                    Toast.LENGTH_SHORT
                ).show()
            is DashMapGptEvent.SetHvac ->
                Toast.makeText(
                    this,
                    "App has set the vehicle temperature to ${event.temperature} ${event.unit}",
                    Toast.LENGTH_SHORT
                ).show()
        }
    }
}

Upon visual rendering of data by the assistant in form of cards, the end user can click on the card to do certain actions. In cases, where the data displayed on the UI represents a custom payload, a tap by the user on the card can be observed using observeMapGptCardEvents.

observeMapGptCardEvents

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                Dash.controller.observeMapGptCardEvents()
                    .collect { /* DashMapGptCardEvent */ event ->
                        // Do something with the DashMapGptCardEvent
                        processMapGptCardEvents(event)
                    }
            }
        }
    }

    fun processMapGptCardEvents(event: DashMapGptCardEvent) {
        when (event) {
            is DashMapGptCardEvent.OnMapGptCardClicked ->
                Toast.makeText(
                    this,
                    "User tapped on the card rendering data identified by ${event.payload}",
                    Toast.LENGTH_SHORT
                ).show()
        }
    }
}

Ready to get started?

Create a free account to start building with Mapbox.

Sign Up

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this page helpful?