User API

The User API is used to interact with Wysp within the scope of a specified User.

It consists primarily of a WebSocket connection for real-time communication.

Authentication

Connections are authenticated with a UserToken, a short-lived bearer token scoped to a single user.

For server-side integrations, you can also authenticate directly as a specified user with your ApiKey and an X-User-Id header.

Authentication: UserToken

Authentication: Acting-as-user

Connection Model

Each active user is represented by 1 or more concurrent WebSocket connections. Responsibilities can be split freely across any number of connections/clients.

A typical setup involves two connections per user:

1. Inference server - subscribes to Prompts, Tools, and Utterances to assemble the agent’s context window and relay tool calls.
2. Navigation device - sends GPS fixes and subscribes to navigation state (route geometry, statements, signals).

Websocket Lifecycle

After establishing a WebSocket connection, the client and server follow a structured initialization sequence:

1. The client opens a WebSocket connection, authenticating via UserToken or ApiKey.
2. The client sends a device.initialize message declaring its deviceId and the event types it wants to receive via subscriptions (e.g. state, prompts, utterances, tools, signals, debug).
3. The server responds with a bootstrap message containing tool definitions and the complete UserState — input preferences, plan, geometry, statements, tool definitions, tool availabilities, and server status. The client should hold this in memory.
4. As state changes occur, the server sends state.delta messages containing only the fields that changed. The client merges each delta into its local copy of the state.

Once initialized, the server streams additional messages based on the client’s subscriptions:

• prompt — Context window prompts for the inference server.
• utterance — Audio messages heard (or to be heard) by the user.
• signal — Control signals (e.g. START_NAVIGATION, OPEN_MIC).
• tools.result — Responses to tool calls (see below).

The client can send messages at any time during the connection:

• device.status — Report battery level and navigation state.
• device.heard_statement — Confirm that a locally-triggered statement was played.
• fixes.append — Send GPS fixes.

Tool Calling

Tool calling follows an RPC pattern over the WebSocket connection.

Calling a tool

{
  "kind": "tools.hypertool", // tool to call
  "data": {
    "requestId": "myrequest-123", // RPC request ID
    "params": {
      "query": "will it be open?",
    },
  },
}

Tool call result

{
  "kind": "tools.result",
  "data": {
    "requestId": "myrequest-123", // ID matches the request
    "result": {
      "value": "Yes - Café Sara is open until 3:30am tonight.", // String response value
      "kind": "SUCCESS", // SUCCESS | FAILURE | BAD_REQUEST | INTERNAL_SERVER_ERROR | REFUSAL
      "nature": "USER_VERBATIM", // OPAQUE | USER_VERBATIM | JSON
      "language": "en-US", // BCP47 language tag
    },
  },
}