---
title: "Report what a viewer shows"
method: PUT
path: "/v1/voice-chat/chat"
tags: ["Voice Chat"]
---

# Report what a viewer shows

`PUT /v1/voice-chat/chat`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/voice-chat/chat`
- Auth: HTTP bearer

A viewer (a browser tab) reports what it shows: the chat, so a spoken turn lands in it while
it shows it (without `conversationId` it shows none), and the page, the workbench tab its
pane shows, the view keys that tab holds and, below 1024px, which of the chat and its pane is
on screen, which every turn's notes describe. A new chat with no record yet names its
project, where the first spoken turn creates it. The latest viewer showing a chat wins.
Only ToolPiper's own app (this Mac's local token) may report.

## Request body

- VoiceChatOnScreenRequest
  - `viewer` string, required: The reporting viewer, stable for its lifetime (1 to 64 ASCII letters, digits and hyphens).
  - `conversationId` string: The chat the viewer shows. Absent when it shows none.
  - `projectId` string: The project of a new chat that has no record yet.
  - `page` 'chat' | 'projects' | 'library' | 'settings' | 'other': The page the viewer shows. Absent when it has not said.
  - `shownWorkbenchId` string: The workbench tab the chat's pane shows on this viewer, which differs from the chat's active tab while the pane holds the person's tab against an outside change. Absent when no workbench is shown.
  - `heldViewKeys` string[]: The view keys the shown workbench holds against an outside change while the person works in it.
  - `narrowTab` 'chat' | 'workbench': Below 1024px, which of the chat and its pane is on screen. Absent in the wide layout.

## Response `200`

Where voice listens after the report

- VoiceChatState
  - `conversationId` string: The chat voice listens to. Absent before there is one.
  - `projectId` string: That chat's project.
  - `listening` boolean, required: Voice is capturing speech for that chat now.

## Other responses

- `400`: The body is not a report, an id is malformed, or a page or narrow tab is not one of its values
- `403`: The caller is not ToolPiper's own app

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)