Websocket Reference

Message Format

All WebSocket messages use the envelope format:

{
  "kind": "message.type",
  "data": { ... }
}

Send

device.ident

Identify the device

Data Schema

type: object

Properties

Name	Type	Required	Description
deviceId	string	yes	Opaque stable identifier for the device. Typically randomly generated and stored on the device, or provided by the operating system.
userAgent	string	no	Freeform text identifying the client platform/software
subscriptions	string[]	yes	Define which kinds of realtime events this device wants to receive.

Example

{
  "kind": "device.ident",
  "data": {
    "deviceId": "2ef22bf5-ab81-43d9-85c0-3cc942c0fda5",
    "userAgent": "Wysp iOS 1.0.47",
    "subscriptions": [
      "utterances",
      "prompts",
      "tools"
    ]
  }
}

device.status

Report the current status of the device

Data Schema

type: object

Properties

Name	Type	Required	Description
batteryLevel	number	no	Device battery level in % (0-100)
isNavigating	boolean	no	Whether or not the device is currently in a “navigating” mode.

Example

{
  "kind": "device.status",
  "data": {
    "batteryLevel": 72,
    "isNavigating": true
  }
}

device.heard_statement

Notification sent by device indicating that is has played a locally-triggered audio statement to the User

Data Schema

type: object

Properties

Name	Type	Required	Description
statementId	string	yes	ID of the heard Statement
playedAt	string	yes	Time at which playback started
interruptedAfterMs	string	yes	Milliseconds of playback completed before interruption

Example

{
  "kind": "device.heard_statement",
  "data": {
    "statementId": "2e4597a8-e879-482a-aa65-7cf0305f189d",
    "playedAt": "2026-01-28T09:00:00.000Z",
    "interruptedAfterMs": "1200"
  }
}

fixes.append

Append fixes

Data Schema

type: object[]

Items

type: object

Properties

Name	Type	Required	Description
lat	number	yes	Latitude in degrees
lng	number	yes	Longitude in degrees
fixedAt	string	yes	Timestamp of the fix
heading	number | null	yes	Estimated direction the user is facing. North at 0 degress, clockwise to 360.
course	number | null	yes	Course over ground in degrees. North at 0 degress, clockwise to 360.
velocity	number | null	yes	Velocity in meters per second
altitude	number | null	yes	Meters above sea level
locationAccuracy	number | null	yes	Accuracy of location in meters
altitudeAccuracy	number | null	yes	Accuracy of altitude in meters

Example

{
  "kind": "fixes.append",
  "data": [
    {
      "lat": 37.7749,
      "lng": -122.4194,
      "fixedAt": "2026-01-28T08:30:00.000Z",
      "heading": 90,
      "course": 88,
      "velocity": 1.2,
      "altitude": 15,
      "locationAccuracy": 5,
      "altitudeAccuracy": 8
    }
  ]
}

state.input.set

Set user state input

Data Schema

type: object

Properties

Name	Type	Required	Description
languages	string[]	no	Array of languages spoken by User, in order of descending preference.
unitSystem	string	no	Preferred unit system for measurements
givenName	string	no	The given name (aka first name / forename / casual spoken name) of the user.
travelMode	string	no	Preferred travel mode
destinations	object & object & object[]	no	Current destination objectives for the user

Example

{
  "kind": "state.input.set",
  "data": {
    "languages": [
      "en-US",
      "nb-NO"
    ],
    "unitSystem": "LOCAL",
    "givenName": "Marius",
    "travelMode": "FOOT",
    "destinations": [
      {
        "kind": "PRESENCE",
        "name": "Home"
      }
    ]
  }
}

tools.search_map

Search the map for places, addresses, businesses, etc.

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.search_map",
  "data": {
    "requestId": "string",
    "params": {
      "query": "coffee shop on the way"
    }
  }
}

tools.add_destination

Add a destination to the trip

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.add_destination",
  "data": {
    "requestId": "string",
    "params": {
      "query": "cafe sara"
    }
  }
}

tools.remove_destination

Remove a destination from the trip

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.remove_destination",
  "data": {
    "requestId": "string",
    "params": {
      "destination": "cafe sara"
    }
  }
}

tools.reorder_destinations

Reorder the destinations within a trip

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.reorder_destinations",
  "data": {
    "requestId": "string",
    "params": {
      "desiredOrder": "Cafe Sara, then Astrup Fearnley"
    }
  }
}

tools.start_navigation

Start navigation mode

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.start_navigation",
  "data": {
    "requestId": "string",
    "params": {}
  }
}

tools.stop_navigation

Stop navigation mode

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.stop_navigation",
  "data": {
    "requestId": "string",
    "params": {}
  }
}

tools.change_travel_mode

Set the travel mode for navigation

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.change_travel_mode",
  "data": {
    "requestId": "string",
    "params": {
      "travelMode": "BICYCLE"
    }
  }
}

tools.get_clarification

Get clarification on which way to go

Data Schema

type: object

Properties

Name	Type	Required	Description
requestId	string	yes
params	object	yes

Example

{
  "kind": "tools.get_clarification",
  "data": {
    "requestId": "string",
    "params": {
      "question": "where do I turn?"
    }
  }
}

Receive

state.bootstrap

On socket connection, server sends the entire state object. The client should hold this in memory, merging in deltas over time as they arrive in state.delta messages

Data Schema

type: object

Properties

Name	Type	Required	Description
input	object	yes	User state input
plan	object | null	yes
geometry	object	yes	GeoJSON describing the user’s current position and planned routes.
statements	object[]	yes	Planned statements for the user
hudItems	object[]	yes	HUD manoeuvre items
server	object	yes	Metadata about the current state of the server from the user’s perspective

Example

{
  "kind": "state.bootstrap",
  "data": {
    "input": {
      "languages": [
        "en-US",
        "nb-NO"
      ],
      "unitSystem": "LOCAL",
      "givenName": "Marius",
      "travelMode": "FOOT",
      "destinations": [
        {
          "kind": "PRESENCE",
          "name": "Home"
        }
      ]
    },
    "plan": {
      "durationSeconds": 852,
      "distanceMeters": 600
    },
    "geometry": {
      "fix": null,
      "triggers": {},
      "routeLines": [],
      "routePoints": []
    },
    "statements": [
      {
        "id": "c04dd717-7e2c-434d-8d31-2f7268e5b51b",
        "transcript": "Turn left at the roundabout.",
        "locale": "en-US",
        "clipId": "18905e54-0091-4e3a-90f7-58d1dcecb913",
        "trigger": {
          "kind": "LOCATION",
          "lat": 37.7749,
          "lng": -122.4194,
          "heading": 90
        }
      }
    ],
    "hudItems": [],
    "server": {
      "isPlanning": false,
      "errorMessage": null,
      "dataAvailability": "FULL"
    }
  }
}

state.delta

Changes to the state object since the last state.bootstrap

Data Schema

type: object

Properties

Name	Type	Required	Description
input	object	no	User state input
plan	object | null	no
geometry	object	no	GeoJSON describing the user’s current position and planned routes.
statements	object[]	no	Planned statements for the user
hudItems	object[]	no	HUD manoeuvre items
server	object	no	Metadata about the current state of the server from the user’s perspective

Example

{
  "kind": "state.delta",
  "data": {
    "input": {
      "languages": [
        "en-US",
        "nb-NO"
      ],
      "unitSystem": "LOCAL",
      "givenName": "Marius",
      "travelMode": "FOOT",
      "destinations": [
        {
          "kind": "PRESENCE",
          "name": "Home"
        }
      ]
    },
    "plan": {
      "durationSeconds": 852,
      "distanceMeters": 600
    },
    "geometry": {
      "fix": null,
      "triggers": {},
      "routeLines": [],
      "routePoints": []
    },
    "statements": [
      {
        "id": "c04dd717-7e2c-434d-8d31-2f7268e5b51b",
        "transcript": "Turn left at the roundabout.",
        "locale": "en-US",
        "clipId": "18905e54-0091-4e3a-90f7-58d1dcecb913",
        "trigger": {
          "kind": "LOCATION",
          "lat": 37.7749,
          "lng": -122.4194,
          "heading": 90
        }
      }
    ],
    "hudItems": [],
    "server": {
      "isPlanning": false,
      "errorMessage": null,
      "dataAvailability": "FULL"
    }
  }
}

utterance

An audio message heard (or to be heard) by the User

Data Schema

type: object

Properties

Name	Type	Required	Description
id	string	yes	UUID
transcript	string	yes	Plain text content of the utterance
language	string	yes	BCP47 language tag
timestamp	string	yes	ISO 8601 UTC Date string
isHeard	boolean	yes	Whether utterance has already been heard by the user
interruptedAt	number	no	Playout progress (0.0-1.0) at which playout was interrupted

Example

{
  "kind": "utterance",
  "data": {
    "id": "c10fed62-9074-41e8-ad3b-a2da249714a2",
    "transcript": "Turn left at the lights.",
    "language": "en-US",
    "timestamp": "2026-01-28T09:00:00.000Z",
    "isHeard": true,
    "interruptedAt": 0.749
  }
}

signal

Control signal

Data Schema

type: object

Properties

Name	Type	Required	Description
signal	string	yes	Control signal

Example

{
  "kind": "signal",
  "data": {
    "signal": "START_NAVIGATION"
  }
}

debug

Debug data

Data Schema

type: object

Example

{
  "kind": "debug",
  "data": {}
}

prompt

Prompt to be integrated into the context window

Data Schema

type: object

Properties

Name	Type	Required	Description
key	string	yes	Opaque key used for prompt replacement
language	string	yes	Natural language of the content
content	string	yes	Content to be included in the user’s overall context window.
timestamp	string	yes	ISO 8601 UTC Date string
ttl	number	no	Number of seconds the content remains valid for

Example

{
  "kind": "prompt",
  "data": {
    "key": "3b8cb7c20",
    "language": "en-US",
    "content": "The user is near the end of Pilestredet and should turn left at the lights. Just before the turn there is a prominent green building on the right. The left turn is subtly uphill.",
    "timestamp": "2026-01-28T09:00:00.000Z",
    "ttl": 20
  }
}

tools.definitions

Set of tool definitions to be included into the context window

Data Schema

type: object

Properties

Name	Type	Required	Description
tools	object[]	yes

Example

{
  "kind": "tools.definitions",
  "data": {
    "tools": [
      {
        "name": "string",
        "title": "string",
        "description": "string",
        "inputSchema": {},
        "outputSchema": {},
        "annotations": {
          "instructions": "string",
          "indications": [
            "string"
          ],
          "contraindications": [
            "string"
          ],
          "posture": "PROACTIVE"
        }
      }
    ]
  }
}

tools.availabilities

List of which tools are currently available

Data Schema

type: object

Properties

Name	Type	Required	Description
available	string[]	yes

Example

{
  "kind": "tools.availabilities",
  "data": {
    "available": [
      "string"
    ]
  }
}