Chat - Orkestia Documentation

Chat

Chat spaces for identity apps. Your end users sign in with their app identity, talk in channels, threads and DMs, and your Staff actors answer inside the same conversation. Every control-plane operation is a workflow

TL;DR

Any identity app can switch on a chat space. One call, buzz.space.enable, runs a chat relay next to the app's App Host site and exposes the chat entry points on the app. buzz.space.publish-chat puts a ready chat page on the site.
People sign in with the identity they already have in your app. Nobody pastes a key. The platform holds each member's chat key and hands it to their browser session only.
Channels, threads, DMs, mentions, reactions, search, pins, attachments. The hosted page covers what people expect from a team chat, and it works on a phone.
Staff actors are members too. Attach an actor that holds an end-user seat in the app, and it answers when mentioned, in a DM, or on every message of a channel you choose. It can also write first.
Actors can answer with cards. Give an actor a DGI responder and it answers with forms, confirm cards, tables, charts, KPI tiles and live cards built on your own workflows. See Structured chat with DGI (part of DGI, Alpha).
Workflows decide who is in and what the chat looks like. Messages never pass through workflows. The relay is the message store, so chat stays fast and your run history stays clean.
It has honest limits. Files require a chat-space member credential. Read Limits for deletion, actor memory, and remaining boundaries.

Orkestia is the backbone that connects software, AI, and the real world. Chat is one of the features that sits on top of it: the same identity apps, the same Staff actors, the same catalog of workflows, now in a conversation.

How a chat space is put together

Identity app (your end users sign in here)
  └─ App Host site
       ├─ Hosted chat page      https://<slug>.app.orkestia.dev (or your domain)
       └─ Chat relay            messages, channels, DMs, media, stored in the app's own Postgres
            ▲
            │  control plane: buzz.* and data.buzz.* workflows
            │  (enable, members, channels, theme, actors, moderation)
            │
       Staff actors attached to the space answer through their own seat

Piece	What it is	You touch it with
Space	The chat of one identity app	`buzz.space.enable`, `buzz.space.status`, `data.buzz.space.get`
Member	A person (an end user of the app) or an attached actor, each with one stable chat key	Console Chat tab, `buzz.member.*`, `data.buzz.member.list`
Channel	An open or private room. DMs are private channels between a few members	`buzz.channel.*`, `data.buzz.channel.list`
Theme	A validated document: brand, colors, layout, feature flags, attachment limits, copy	`buzz.theme.*`, `data.buzz.theme.get`
Attachment (actor)	The link between a Staff actor and a space: triggers, reply ceiling, reply mode, responder (Staff, DGI or hybrid)	`buzz.actor.*`, `data.buzz.attachment.list`

The same relay is the Buzz addon on App Host. A chat space is the managed way to use it for an identity app: the platform owns the relay's owner key, keeps the member roster in line with your app's seats, and publishes the chat page for you.

Who can do what

Caller	Can
A person in your organization, signed in to the console or calling the API as themselves	Enable and publish the chat, edit the theme, manage members and channels, attach actors. Moderation (ban, timeout, deleting a message), renaming someone, the admin reads and internal mode need an organization admin
An end user of the app, signed in on the chat page	Open the chat, post, react, search, create or join channels when the space allows it, set their own display name, turn missed-message email off
A Staff actor attached to the space	Answer when addressed, and post or open a DM as itself. It cannot attach actors, change roles, open channels or moderate

Every admin verb refuses agents, agent sessions and end users, so an actor sitting in the chat can never promote itself or change the space.

Guides

Enable and publish

Turn the chat on for an identity app and publish the hosted chat page.

Theme and customization

Draft, preview, publish and roll back the look, the feature flags, the copy and the attachment limits.

Members and moderation

Invite people, roles, display names, suspend, timeout, ban, remove, rotate a key, reconcile.

Channels

Org channels, channels your members run, private channels.

Using the chat

DMs, threads, mentions, reactions, search, pins, unread counts, attachments, missed-message email, mobile.

Actors in chat

Attach an actor, triggers, progress lines, the tool trace, quick replies, handoff to a person, several actors, messages that start from outside.

Internal support actor

An actor that answers your own team with your organization's tools.

API and console

Which chat reads and verbs you can call, and the console Chat tab.

Limits

What the chat does not do yet, stated plainly.

Structured chat with DGI

Actors that answer with forms, confirm cards, tables, charts and live cards. Choose hosted, embedded, custom or API.

Option A: hosted chat

Turn it on with workflows only, step by step, with a worked example.

Option B: embed the component

The chat with every card built in, inside your own React app.

Option C: custom client

The wire contract: blocks, tags, renderers, answers and validation.

Option D: any app or API

The same cards from four workflows, with no chat space: profile, turn, respond.

Responder reference

Every buzz.actor.set-responder field, hybrid handoff, default inputs, troubleshooting.

Cards, live updates and proactive posts

Refresh, live cards, row actions, the / palette, and cards your workflows post.

Security model

Who DGI runs as, the structured confirm, and why cards cannot be forged.

Card catalog

Every card, from forms and confirms to data grids, diagrams and the query console.

Living Surfaces

Pages of live cards that DGI grows, keeps current and retires, streamed to the browser.

Ask your AI assistant

prompts

List the chat spaces in my organization with data.buzz.space.list and show each one's status.

For my identity app "<app name>", run buzz.space.status and tell me whether the relay is ready and the members are in sync.

Show me the members of my chat space with data.buzz.member.list, and flag anyone who is suspended, banned or timed out.

Which actors are attached to my chat space, what wakes them, and how many replies has each sent in the last hour? Use data.buzz.attachment.list.

Explain the difference between buzz.space.disable and buzz.space.delete before I run either.

For AI agents

Need	Do this
Find the space	`data.buzz.space.list`, or `data.buzz.space.get` with `identity_app_uuid`. Never guess a `space_uuid`
Health	`buzz.space.status` (read-only): relay readiness and member convergence
Who is in it	`data.buzz.member.list` for admins, `data.buzz.member.directory` for a people-and-actors view with no platform ids
Safe to start	Everything in `data.buzz.*` that is featured, `buzz.space.status`, `buzz.theme.validate`, `buzz.media.list`
Confirm with the user first	`buzz.space.enable`, `buzz.space.publish-chat`, `buzz.theme.publish`, every `buzz.member.` and `buzz.channel.` change, `buzz.actor.attach`, `buzz.actor.set-responder`, `buzz.actor.post-view`, `buzz.bridge.sync`
Never without explicit confirmation	`buzz.space.delete`. It removes the relay and its volumes and cannot be undone
Callers	Admin verbs refuse agents and agent sessions. If you run as an agent token, hand the exact call to a person instead
Messages	There is no workflow that reads message content. End users post from their own chat client; actors post with `buzz.message.post` or `buzz.actor.notify`

GCE

Runner group kind backend_type=gce — one Google Compute Engine VM per execution (beta)

Enable and publish

Turn on a chat space for an identity app with buzz.space.enable, publish the hosted chat page with buzz.space.publish-chat, and let your end users sign in with their app identity