Skip to main content

​
Brand and Launch Your Hosted Help Center

Devotel Orbit hosts a public help center for your workspace: the articles you publish from your knowledge base, browsable categories, full-text search, your logo and colors, and a visitor ticket form — all served from orbit.devotel.io/help without you standing up a site. This guide walks the portal from empty to launched: enable it, brand it, structure its taxonomy, publish articles into it, and wire the ticket intake into your inbox. The endpoint paths below are relative. Send them against https://api.orbit.devotel.io/api/v1.
The public help center is distinct from the internal knowledge bases your agents ground on. The internal base keeps every document private; the help center only ever exposes documents you explicitly flag public and publish.

​
What the portal serves

Everything a visitor can reach lives under /api/v1/public/help, and everything there is tenant-scoped by the ?org=<your-slug> query parameter:
  • Articles — published markdown documents from your knowledge base that you flagged public. This is the self-serve content layer.
  • Categories and sections — a two-level taxonomy that groups articles for browsing (“Browse by topic”).
  • Full-text search — substring matching across title and body, title matches ranked first.
  • Branding — your logo, primary and secondary colors, header links, and an opt-out “Powered by Orbit” credit.
  • Visitor ticket form — an unauthenticated submission endpoint that lands in your inbox as a ticket, with a capability token the visitor uses to track their request without an account.
The hosted frontend at orbit.devotel.io/help renders these endpoints; you can also embed the same calls in your own site if you want a fully custom page. Source content lives in the internal knowledge base; the help center is a projection of the subset you publish.

​
1. Set up the portal

The portal needs no explicit enablement step — it serves whatever you have published. What you do before launch is branding and (optionally) a custom domain. Brand it. The public-safe branding subset is a small set of fields: help-center logo, primary and secondary colors, header links, and whether the “Powered by Orbit” credit shows. Set them on your organization’s branding settings (dashboard Settings → Branding, or the branding API). Set only the help_* subset; the portal never exposes your dashboard logo, support email, or custom domain on this unauthenticated surface. Unset fields fall back to the platform default theme.
The response carries logo_url, primary_color, secondary_color, header_links, and show_powered_by. The hosted help page reads this once on load. To hide the credit, explicitly set show_powered_by to false in your branding settings — an unset value shows it. Put it on your domain. To serve the help center from help.acme.example instead of orbit.devotel.io/help, register a custom domain and let the platform issue and maintain the certificate. Walk through Custom domains and managed SSL: you register the hostname, point a CNAME, and the TLS certificate provisions automatically. The help center’s ?org= query parameter keeps the tenant scope uniform across the platform domain and your custom domain.

​
2. Organize categories

Categories and their nested sections are a two-level taxonomy over the knowledge documents you publish. The public taxonomy tree endpoint returns every public category with its public sections and a rolled-up article count:
Each element carries name, slug, description, position, and article_count, plus a sections array of the same shape. Only categories and sections flagged is_public appear; a category with only draft articles renders with article_count: 0. Manage the taxonomy from the knowledge-base side of your workspace (the dashboard Agents → Knowledge base page, or the knowledge API): create the category, set its slug and position, and flip it public when it is ready. A private category hides every article inside it from the public surface, even when individual articles are flagged public — you keep a single flip instead of unpublishing each article. Start with a small, browsing-oriented set — two to six categories that match how a visitor asks for help, not your internal org chart. Common shapes: “Getting started”, “Billing and account”, “Troubleshooting”. Reorder via the position field; rename freely — the slug is the stable key.

​
3. Author and publish articles

Articles come from your knowledge base. The full source-editing lifecycle — draft, review, approve — is in Build and Maintain an AI Knowledge Base; the help center is where a document goes after you flag it public and publish-ready. The lifecycle the portal sees:
  1. Draft in the knowledge base. Drafts and unapproved versions never reach the public surface.
  2. Flag the document public (is_public = true) on the document — this is the explicit opt-in. (kd-publication flow on the dashboard knowledge-page.)
  3. Publish — the document status moves to ready, which is the gate the portal queries. An article whose category is private stays hidden even when the article itself is public.
Each article is browseable by a slug (lowercase letters, digits, hyphens), carries a summary in its metadata, and is rendered from its raw markdown body by the hosted page. Unpublish by clearing the public flag or moving the status off ready; a slug miss on the portal returns an empty list rather than an error, so visitors re-render gracefully.

​
4. Wire full-text search

The portal’s search endpoint matches substring patterns across the title and body of your published, public articles:
Title matches rank ahead of body matches, then by recency. The response is data.results (slug, title, summary, view count) plus the echoed query. Search is intentionally substring-based — the vector-similarity search your internal knowledge bases use is not exposed on the public surface, so a visitor can’t probe it for nearby private content. Analytics. Every article detail view increments a view_count you can read back in the list and detail responses, and the visitor ticket form captures which article slugs the visitor read before filing. Together those tell you which topics drive traffic and which gaps turn into tickets. Use sort=most-viewed on the article list to surface your most-read content.

​
5. Branding and theming

The branding subset the portal exposes is deliberately narrow — proof that an unauthenticated surface doesn’t leak your wider white-label config:
  • logo_url — the help-center logo. Stored as a signed link; the portal re-mints a fresh signed URL on each branding read so the link never expires in front of a visitor.
  • primary_color / secondary_color — accent colors the hosted page applies to header and links.
  • header_links — up to your own nav items (label + URL), rendered in the portal header.
  • show_powered_by — the “Powered by Orbit” credit. Explicitly set false to hide it; unset means shown.
For custom-domain serving, the help page renders on the same registered hostname you walked through in Custom domains and managed SSL — one CNAME, one managed certificate, no upload.

​
6. Capture visitor tickets

The ticket endpoint is unauthenticated by design — a visitor who cannot self-serve needs a path to support before signing in:
Body fields: org (required), subject (3–200 chars), body (10–16,384 chars), email (format-checked at the edge), optional name, locale, and articleSlugs — the slugs of articles the visitor read before filing, so your agent sees which self-serve paths were tried without re-asking. The 201 response returns the ticket receipt and a status_token. The visitor uses that token plus the ticket id to track the request without an account:
The token is a read-only capability over the ticket id — no session is created, and a wrong token returns the same generic 404 as a missing ticket so the surface never enumerates ids. Abuse posture. The endpoint is rate-limited more tightly than reads because every submission lands in your operator queue. Visitor IP addresses are hashed before persistence — never stored raw — and we deliberately do not auto-resolve the submitted email to a contact, because the address is unverified; an operator links it after review. The ticket lands in your inbox ticket queue as a public_form-source ticket. Run the same routing you’d run for any web-form intake — auto-assignment, SLA, queue routing — per Inbox tickets workflow. If you also accept inbound email, the from-address and routing rules follow the pattern in Audience senders hub; the help-center form is the no-account complement to that mailbox intake.

​
7. API walkthrough

The six public help-center calls you wire against — full endpoint shapes in the Help Center API reference: Two more complete the surface: GET /public/help/branding reads the public-safe branding, and GET /public/help/tickets/:id lets the visitor track their ticket with the capability token — both are covered above, and the API reference lists every call. List articles:
Submit article feedback:
Feedback is the only write other than tickets; the article existence is verified before the vote is recorded so junk articleId values don’t inflate your metrics.

​
8. Where the nav lands

The help center is wired into the workspace alongside the other inbox and knowledge surfaces. Use the dashboard Agents → Knowledge base page to author and flag documents public, the dashboard Settings → Branding page to theme, and the hosted /help page to preview exactly what a visitor sees. Keep the launched URL handy: https://orbit.devotel.io/help?org=<your-slug>, or your custom domain if you registered one.

​
Troubleshooting

​
See also