Skip to main content

​
Using Orby, the in-dashboard operator assistant

Orby is the assistant built into the Orbit dashboard. It answers operator questions in natural language, grounds its answers in your workspace data and the Orbit product documentation, and — when a request implies a change — proposes an action for your explicit approval instead of acting silently. This guide covers the operator experience: opening the panel, how Orby grounds answers, the approval posture on data-changing actions, and what happens under degraded conditions. For the underlying HTTP contract a custom integration uses, see the Orby API reference.

​
What Orby is

Orby is a chat panel for operators — the people who run your Orbit workspace day to day. Ask it a question (“how many conversations are unassigned right now?”), ask it to orient you (“where do I set quiet hours?”), or ask it to do something (“reassign this conversation to Maya”). Orby classifies the intent of each message, reads the relevant tenant data, and replies in the same panel. Two properties define the surface:
  • Operator-facing only. Orby runs in the context of the signed-in dashboard user. There is no server-to-server API-key path: a request authenticated with an API key is rejected with 403 ORBY_SESSION_REQUIRED. Every turn is scoped to your organization, your role, and your own threads.
  • Same permissions, not more. Orby acts under your operator role. It cannot reach anything your role could not reach through the dashboard or API, and every data-changing action it proposes runs through the same authorisation checks as if you had clicked the equivalent control yourself.

​
Open the Orby panel

Orby is available anywhere in the dashboard:
  • Click the Orby button (sparkles icon) in the top bar, next to the help and notifications cluster, or
  • Press Ctrl+J (Windows) / Cmd+J (macOS).
The panel slides out as a drawer over the current page. Each conversation is a thread: start a new one by simply typing, or open Past chats in the panel to pick up an earlier thread — threads you create are listed newest-first and persist across sessions. A thread belongs to you: other operators in your organization cannot list or read it, and vice versa. Orby sees which dashboard page you are on. Asking “summarize this thread” from inside a conversation, or “what does this queue cost?” from a queue detail page, gives Orby a starting context — you can always override it by spelling out the target in your message.

​
Knowledge-base grounding

Orby is grounded in two sources, so its answers are about your workspace, not a generic textbook:
  1. Live tenant data. When a question is operational — counts, statuses, a specific conversation — Orby reads the relevant records under your tenant, live, and cites them in the reply.
  2. The Orbit product documentation. Orby searches the same documentation corpus this site is built from, under /orby/kb. That is the “where do I configure X?” path: Orby maps a plain-language description to the dashboard route where the setting lives and links the matching doc page, instead of paraphrasing from memory.
You can also use the documentation search directly — Cmd+K anywhere in the dashboard opens the same docs-search surface Orby uses, for the moments you want a link rather than a conversation. Answers that come from the docs include a link to the source page; answers that come from tenant data are scoped to what your role can already read. If Orby cannot ground an answer, it asks a clarifying question instead of guessing.

​
Tool actions: proposal and approval

When a request would change data, Orby does not act immediately. It proposes the action and pauses:
  1. Orby renders a pending action card in the chat: the tool it intends to run (“send an SMS”, “reassign this conversation”, “pause this campaign”), the exact arguments it will use (recipient, body, target conversation), and an estimated cost where one applies.
  2. You approve to execute, or reject to cancel. Replying in chat with a plain confirm / yes / cancel resolves through the same path as the buttons — either way lands in the audit trail identically.
  3. A pending action expires after 5 minutes. If the countdown elapses, the action is cancelled and Orby confirms nothing ran.
  4. Approvals are protected against replays and races: approving an already-resolved action is rejected, and a concurrent second approval is refused. Between proposal and approval Orby also regrounds the tool arguments — if the underlying data changed while you were deciding (the conversation got reassigned by a teammate, the recipient list changed), the action does not run on stale inputs.
This is the same four-eyes discipline as the OTP approvals in Verify: a sensitive change requires a second, explicit confirmation on the exact payload, and the trail records both the proposal and the decision. Some actions additionally carry an undo window — for example, a sent message can be rolled back inside its short grace period, and the action then shows as undone in your history. Read-only work — searches, counts, summaries, drafts — never pauses for approval. Only effects that change data do.

​
Session-only guard and degraded behaviour

Two resilience properties are worth knowing before you rely on Orby in production: Session guard. Every Orby request must authenticate as a signed-in dashboard session. An API-key request — whether the key arrives as X-API-Key or as a dv_* Bearer token — is rejected before any handler runs with 403 ORBY_SESSION_REQUIRED. A leaked or over-permissioned API key therefore cannot drive Orby’s tool execution or knowledge-base surface; there is no path around the operator session. Availability degradation. If Orby’s backing store is briefly unavailable (for example, during a database failover), the read side degrades instead of failing hard:
  • The Past chats thread list renders as an empty list, equivalent to an operator with no threads, rather than an error page.
  • Reopening a thread renders as an empty message list, not a 503.
Once the store recovers, your real threads reappear — nothing is deleted by the degraded view. The turn endpoint itself (sending a new message) still reports a real error if the backend is down, because a failed turn must never pretend it ran. Rate limits also apply per operator: if you hit the turn limit, Orby tells you how long to wait before retrying.

​
Examples

A few representative flows: Draft and send an SMS. You: “Send an SMS to +15555550100 saying their order shipped.” Orby composes the message, renders a pending action card with the recipient, body, and estimated cost, and waits. Approve, and the message queues; the card shows the queue confirmation. The same flow works in reverse for inspection: “Show me the last outbound SMS to that number.” Reassign a conversation. From a conversation page: “Reassign this conversation to Maya.” Orby proposes the reassignment with the target agent and conversation visible on the card. Approve, and the assignment changes. If the conversation was already reassigned while the proposal was open, the approval regrounds and refuses to run on stale data — resend the request to get a fresh proposal. Summarize a thread. Open any conversation and ask “Summarize this thread in three bullet points.” Orby reads the conversation and replies inline. Summaries, counts, and searches are read-only, so they never trigger an approval step. Find a setting. “Where do I set quiet hours for SMS campaigns?” Orby answers with the dashboard route and the docs link — click through, and the conversation keeps the answer for later reference in Past chats.

​
Security and compliance posture

  • Authenticated as you. Every Orby call carries your operator JWT and inherits your Orbit role and scopes. Orby has no separate identity and no hidden privilege; anything it does, your role could already do.
  • Scoped authorization. The tool actions Orby can propose run inside the authorization-mandates framework — scoped, capped, and revocable grants with a consent digest verified at act time. Nothing executes outside that gate: a tool action without a valid, in-scope mandate is refused before any side effect.
  • Auditable end to end. Proposals, approvals, rejections, expiries, and undo events are all audit-logged with the operator identity, so a compliance review can reconstruct who approved exactly which payload.
  • Tenant isolation. Threads, pending actions, and KB results are scoped to your organization. Cross-tenant reads are impossible by construction, not by policy.
The controls above are the tenant-owned posture — you configure roles, scopes, and mandates; Orbit enforces them.

​
See also