ChatRoomInsightResult chat.room-insight-result@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
chat
Visibility
public
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/chat/room-insight-result.v1.json

chat.room-insight-result@1: the answer of GET /api/v1/rooms/:id/insight on OpenVibe.Chat, public (no account, as the room itself is readable). One shape for every room: Global (id `global`) first, then a server's channels and the rooms people make. The overview is the summary OpenVibe.Chat's chat-AI job keeps (the same schedule, window and budget rules as Live's, only when there were new messages); it reads only the messages of people who allowed AI use of them (network.consent@1, purpose ai.train on kind chat), so an overview never quotes someone who did not. state is `ready` when the overview is fresh, `quiet` when there is nothing new to say (text and topics empty, the timeline keeps history), and `off` when the room's owner has not turned the insight on (private rooms; never a DM). A room the rollout does not cover answers 404. Timestamps are Chat's UTC `YYYY-MM-DD HH:MM:SS` (ov_now()), or null.

Fields

FieldTypeRequiredDescriptionConstraints
overviewobjectyes
  • no other fields
overview.textstringyesThe overview written for someone arriving now, in plain prose; empty when state is quiet or off.
  • maxLength 2000
overview.topicsarray of objectyesThe words the window kept coming back to, most mentioned first. Empty when state is quiet or off.
  • maxItems 20
  • items: no other fields
overview.topics[].labelstringyes
  • minLength 1
  • maxLength 60
overview.topics[].countintegeryesHow many messages of the window mentioned the topic.
  • minimum 1
overview.peopleintegeryesHow many different people wrote in the window the overview reads.
  • minimum 0
overview.messagesintegeryesHow many messages the window held (the ones the summariser was allowed to read).
  • minimum 0
overview.fromstring | nullyesThe window's first message time.
overview.tostring | nullyesThe window's last time, which is when the job last looked.
overview.updated_atstring | nullyesWhen the overview row was last written.
timelinearray of objectyesThe room's notable moments, newest first. History survives a quiet window.
  • maxItems 60
  • items: no other fields
timeline[].atstringyesWhen it happened, Chat's UTC `YYYY-MM-DD HH:MM:SS`.
timeline[].kindstringyesWhat kind of moment: `moment` for a notable thing the summariser recorded, `event` for a non-chat activity (a donation, a clip), `message` for a line it picked out.
  • maxLength 20
timeline[].titlestringyes
  • minLength 1
  • maxLength 140
timeline[].textstringyes
  • maxLength 400
timeline[].message_idinteger | nullyesThe message it came from, when it is one message; null for a summary of several.
  • minimum 1
stateenumyesready: the overview above is fresh. quiet: nothing new to say; said as quiet, never invented. off: the room's owner has not turned insight on.
  • one of "ready", "quiet", "off"

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: quiet
{
  "overview": {
    "text": "",
    "topics": [],
    "people": 0,
    "messages": 0,
    "from": null,
    "to": null,
    "updated_at": null
  },
  "timeline": [],
  "state": "quiet"
}
Valid: ready
{
  "overview": {
    "text": "People are planning the Friday stream and comparing two capture cards. Someone asked for the clip of the ending, and the room voted for a Saturday replay.",
    "topics": [
      {
        "label": "capture card",
        "count": 7
      },
      {
        "label": "friday stream",
        "count": 4
      }
    ],
    "people": 9,
    "messages": 42,
    "from": "2026-11-10 08:10:00",
    "to": "2026-11-10 09:45:00",
    "updated_at": "2026-11-10 09:45:03"
  },
  "timeline": [
    {
      "at": "2026-11-10 09:40:12",
      "kind": "moment",
      "title": "The Saturday replay",
      "text": "The room agreed on a replay at the weekend.",
      "message_id": 90214
    },
    {
      "at": "2026-11-10 09:12:44",
      "kind": "event",
      "title": "A donation came in",
      "text": "goosely gave 500 OpenCoins for the capture card fund.",
      "message_id": null
    }
  ],
  "state": "ready"
}
Rejected: bad-state
{
  "overview": {
    "text": "A room whose state is not one of the three.",
    "topics": [],
    "people": 1,
    "messages": 1,
    "from": null,
    "to": null,
    "updated_at": null
  },
  "timeline": [],
  "state": "busy"
}
Rejected: no-timeline
{
  "overview": {
    "text": "An overview without its timeline.",
    "topics": [],
    "people": 0,
    "messages": 0,
    "from": null,
    "to": null,
    "updated_at": null
  },
  "state": "ready"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('chat.room-insight-result@1', value);   // { valid, errors: [{ path, message }] }