Orby operator assistant: natural-language settings lookup

One of Orby’s load-bearing skills is answering a “where do I configure X?” question with the dashboard route where the setting actually lives, not a paraphrase from memory. The settings-resolution helper behind it is ranked, grounded, and available to every signed-in operator role — from the billing-only viewer to the super-admin. For the full operator experience (panel, threads, approvals), see Using Orby in the dashboard; for the endpoint contract, see the Orby API reference. This guide walks through the settings-lookup surface itself: where it sits in the dashboard, what a ranked match contains, how to phrase the lookup, how the knowledge base degrades while it initializes, and how tool actions pair with the lookup.

Where Orby lives in the dashboard

Orby is available on any dashboard page — open the panel with the Orby button (sparkles icon) in the top bar, or Ctrl+J / Cmd+J. Inside the panel, every question goes through Orby’s operator session, and settings lookups are part of the panel’s read-only surface. Beyond the panel, the Cmd+K docs-search shortcut anywhere in the dashboard opens the same knowledge-base surface that powers settings lookup. Every Orby request runs in the context of the signed-in operator:

Operator-session auth only. Orby runs on the operator-session auth layer — requests authenticated with an API key (X-API-Key or a dv_* Bearer token) are rejected with 403 ORBY_SESSION_REQUIRED before any handler runs. There is no server-to-server path.
Any operator role can look up a setting. The owner, admin, developer, viewer, and billing roles all reach the lookup surface — a billing-only operator can ask “where do I set quiet hours?” and get the route back. Super-admin-only endpoints in the knowledge base (reindex, status) exist for index maintenance, not for lookup.
Same permissions, not more. Orby can only reach the settings and pages the operator’s role could already navigate to. There’s no separate assistant identity.

Natural-language settings resolution

When you ask Orby a question of the form “Where do I configure X?” — or pick a result from the Cmd+K docs search — Orby resolves the free-text query against the knowledge base and returns ranked matches. Each match carries:

Field	What it tells you
`setting_path`	Dotted path of the setting in the workspace config model (`settings.messaging.quiet_hours`)
`dashboard_url`	The dashboard route to click through (`/settings/messaging#quiet-hours`)
`label`	The human-readable setting name, as shown in the dashboard
`description`	A one-line summary of what the setting controls
`doc_url`	The doc page the match was grounded on
`snippet`	The excerpt from that page Orby used
`score`	Relevance score (0–1) the ranking engine returned

The endpoint behind this is POST /api/v1/orby/kb/find-setting. Public endpoint and field names stay as-is — the table above states the order the JSON body arrives in.

Phrasing the lookup

Use natural language, not setting names — “Where do I set quiet hours for SMS campaigns?” resolves better than quiet_hours. The endpoint rewrites the query with a settings bias, so the prose form finds the match the keyword form would.
Ask for one thing at a time. “Where do I set quiet hours and quiet hours for voice?” splits the ranking.
The description field accepts up to 500 characters — long multi-sentence questions still resolve, but the first sentence carries most of the weight.
Ask a follow-up command (“Where do I set X?”) rather than a statement (“quiet hours”) — the ranked matcher is tuned for intent phrasing.

A few worked prompts and the ranked-match shape they return: “Where do I set quiet hours for SMS campaigns?”

{
  "data": {
    "matches": [
      {
        "setting_path": "settings.messaging.quiet_hours",
        "dashboard_url": "/settings/messaging#quiet-hours",
        "label": "Quiet hours",
        "description": "Pause outbound campaigns during set hours.",
        "doc_url": "https://docs.orbit.devotel.io/compliance/quiet-hours",
        "snippet": "Set the hours during which campaigns pause…",
        "score": 0.9
      }
    ]
  },
  "meta": { "request_id": "req_orby_qh01", "timestamp": "2026-10-01T12:00:00Z" }
}

“Where do I change the welcome message that plays in the ACD queue?”

{
  "data": {
    "matches": [
      {
        "setting_path": "settings.voice.acd_queues.welcome_prompt",
        "dashboard_url": "/settings/voice/queues#welcome",
        "label": "Queue welcome message",
        "description": "Greeting that plays once when a caller enters the queue.",
        "doc_url": "https://docs.orbit.devotel.io/voice/queues",
        "snippet": "The welcome prompt plays before the caller is offered to an agent…",
        "score": 0.86
      }
    ]
  },
  "meta": { "request_id": "req_orby_wl01", "timestamp": "2026-10-01T12:00:01Z" }
}

“Where do I upload the 10DLC brand documents?”

{
  "data": {
    "matches": [
      {
        "setting_path": "settings.messaging.10dlc.brand",
        "dashboard_url": "/settings/messaging/10dlc#brand",
        "label": "10DLC brand registration",
        "description": "Upload brand identity and vetting documents for US carrier registration.",
        "doc_url": "https://docs.orbit.devotel.io/messaging/10dlc-registration",
        "snippet": "Register your brand with the Campaign Registry for US A2P throughput…",
        "score": 0.88
      }
    ]
  },
  "meta": { "request_id": "req_orby_10dlc", "timestamp": "2026-10-01T12:00:02Z" }
}

The exact fields and error envelope are in the Orby API reference — Find a setting.

Tool actions: read-only lookup, guarded execution

The settings lookup is read-only — it proposes nothing and never pauses for approval. Orby’s tool actions run when a turn’s intent is a change (send a message, reassign a conversation, pause a campaign) and they pause behind the same approval gate described in Using Orby. The knowledge-base endpoints power both sides of the surface:

GET /api/v1/orby/kb/search — free-text docs search (query: 1–500 chars, optional section/category filter).
POST /api/v1/orby/kb/find-setting — natural-language settings resolution (description: z.string().min(1).max(500) — one to 500 characters).
Both endpoints are available to any authenticated operator role, and both scope their audit rows to the organization, tenant, and operator.
POST /kb/reindex and GET /kb/status are super-admin-only maintenance endpoints; they appear in the operator surface only in the rare event of a stuck index, never in the lookup flow itself.

Examples of safe, allowed lookups — all read-only, all resolvable for any role:

“Where do I configure quiet hours?”
“Where do I upload my 10DLC brand documents?”
“Where do I see the campaign cost per send?”
“Where do I pause an ACD queue?”

Degradation behavior: `kb_outage_hint`

While the knowledge base is initializing — the orbit_docs Qdrant collection is cold, or being reindexed — the lookup does not error. Instead it returns an empty matches array plus a kb_outage_hint:

{
  "data": {
    "matches": [],
    "kb_outage_hint": "Orbit's knowledge base is temporarily initialising or reindexing. Try again shortly."
  },
  "meta": { "request_id": "req_orby_cold01", "timestamp": "2026-10-01T12:00:00Z" }
}

Treat an empty result with this hint as a temporary cold index, not as “Orby thinks nothing matches.” Operators should:

Wait a few seconds and re-ask — the index typically initializes on the first hit after a deploy or a reindex.
If you’re a super-admin, check GET /api/v1/orby/kb/status for index health (total and stale chunk counts, last run, cache hit rate).
If the hint persists for more than a few minutes, the worker that owns reindex is likely unavailable — escalate to your super-admin to trigger POST /api/v1/orby/kb/reindex once the worker is back.

In parallel, if Orby’s backing store drops briefly (a database failover), the thread list and reopened threads degrade to empty shapes — not errors — and recover when the store returns. A failed turn never pretends to run; the write side reports a real error. See Orby in the dashboard — degraded behaviour.

FAQ

Am I rate-limited on lookups? Lookups share Orby’s per-operator limits. POST /assistant (a free-form turn that also does settings lookup) is 60 turns per minute per operator; exceeding it returns 429 ORBY_RATE_LIMITED with a Retry-After seconds header. Knowledge-base search / find-setting calls are not separately limited beyond this — they cost one turn each from the dashboard panel. What queries are recorded? Every lookup is audit-logged with orby.kb.find_setting (or orby.kb.searched) — the organization, tenant, operator identity, query text (truncated to 200 characters), result count, latency, and the cold-index flag. Audit rows are for SOC-2 / ops reconstruction only; they never see the outside of your workspace. Do trial orgs get access? Yes. Orby’s settings lookup is on for every organization, including trials — any authenticated operator role can use it. The only role-gated endpoints are the super-admin maintenance pair (reindex, status), which no trial org typically needs. Contacts, threads, and query logs stay scoped to the trial tenant.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Orby operator assistant: natural-language settings lookup

Orby operator assistant: natural-language settings lookup

Where Orby lives in the dashboard

Natural-language settings resolution

Phrasing the lookup

Tool actions: read-only lookup, guarded execution

Degradation behavior: `kb_outage_hint`

FAQ

See also

​Orby operator assistant: natural-language settings lookup

​Where Orby lives in the dashboard

​Natural-language settings resolution

​Phrasing the lookup

​Tool actions: read-only lookup, guarded execution

​Degradation behavior: kb_outage_hint

​FAQ

​See also

Orby operator assistant: natural-language settings lookup

Where Orby lives in the dashboard

Natural-language settings resolution

Phrasing the lookup

Tool actions: read-only lookup, guarded execution

Degradation behavior: `kb_outage_hint`

FAQ

See also