Public Chatbot

Any project with Long-Term Memory activated can publish a Public Chatbot — a knowledge assistant that answers questions from that project's knowledge graph. Toggle it on in the project settings, then either embed the ready-made chat widget on your website or integrate via the JSON API.

Under the hood, the chatbot is a scoped-down version of Doorkeeper. Where Doorkeeper sees your entire organization and can manage projects, trigger workflows, and coordinate agents, the Public Chatbot focuses on one thing: answering questions from a single project's knowledge base — no login required, no access to your organization's internal data.

How It Works

When you enable the Public Chatbot on a project, ORQO generates an API token and gives you three ways to connect:

1. Embeddable widget — A <script> tag you drop into any website. Use it as a floating chat button, or add the inline attribute to embed it directly into your page layout.
2. JSON API — A REST endpoint for building custom chat interfaces or integrating into existing applications.
3. API token — For authenticating requests from either integration method.

Behind the scenes, the chatbot runs the same AI conversation system as Doorkeeper, but with a restricted tool set and access limited to the project's knowledge graph.

Enabling the Chatbot

1. Open your project in ORQO
2. Toggle Long-Term Memory on (required — the chatbot needs a knowledge base to query)
3. Toggle Public Chatbot on
4. The API token, embed code, and JSON API endpoint appear automatically

Configuration

Greeting Message

The first message visitors see when they open the chat. Defaults to a generic greeting — customize it to match your brand or use case.

Personality

Optional instructions that shape the chatbot's tone and behavior. For example:

• "Be friendly and concise. Use simple language."
• "You are a technical support agent. Always link to relevant documentation."
• "Answer in the same language the user writes in."

Embeddable Widget

Drop two lines into your HTML to add the chatbot to any website:

<script src="https://orqo.ooopps.com/chatbot-widget.js"></script>
<orqo-chat token="your_project_token"></orqo-chat>

The widget is a self-contained Web Component with Shadow DOM — it won't interfere with your site's styles, and your styles won't leak into it.

Inline Mode

Instead of a floating launcher, you can embed the chatbot directly into your page layout. Add the inline attribute and wrap the element in a sized container:

<script src="https://orqo.ooopps.com/chatbot-widget.js"></script>
<div style="height: 500px;">
  <orqo-chat token="your_project_token" inline></orqo-chat>
</div>

In inline mode, the chatbot fills its parent container — no launcher icon, no close button, always visible. The parent element controls the size. This is ideal for dedicated support pages, help centers, or any layout where the chat is the primary content.

Widget Options

Attribute	Default	Description
token	—	Project chatbot token (required)
greeting	—	Initial message shown to visitors before they type
position	bottom-right	bottom-right or bottom-left (floating mode only)
theme	light	light or dark
open	—	Start expanded (floating mode only; add attribute without value)
inline	—	Inline mode: fills parent container, no launcher (add attribute without value)
chromeless	—	Raw chat interface: no header, footer, shadow, border, or background (add attribute without value)

Chromeless Mode

For deep integration where the host page provides all surrounding UI, use chromeless. This strips away all widget chrome — header bar, footer, box shadow, border, border radius, and background — leaving just the message list and input field:

<div style="height: 400px;">
  <orqo-chat token="your_project_token" chromeless></orqo-chat>
</div>

Chromeless mode implies inline mode (no launcher, fills parent container). You can still override individual styles with CSS custom properties — for example, setting --orqo-surface to match your page's card color for message bubbles.

Theming

Customize the widget's appearance with CSS custom properties on the <orqo-chat> element:

orqo-chat {
  /* Core */
  --orqo-primary: #3b82f6;        /* Accent color */
  --orqo-bg: #ffffff;              /* Chat background */
  --orqo-surface: #f3f4f6;        /* Message bubble background */
  --orqo-text: #111827;            /* Text color */
  --orqo-muted: #6b7280;          /* Secondary text */
  --orqo-font: system-ui;         /* Font family */
  --orqo-radius: 16px;             /* Border radius */
  --orqo-width: 400px;             /* Panel width (floating mode) */
  --orqo-height: 600px;            /* Panel max height (floating mode) */

  /* Chrome control */
  --orqo-shadow: none;             /* Panel box-shadow (default: subtle drop shadow) */
  --orqo-border: none;             /* Panel border (default: none) */
  --orqo-header-bg: #3b82f6;      /* Header background (default: primary color) */
  --orqo-header-text: #ffffff;     /* Header text color */
  --orqo-footer: none;             /* Footer display — "none" hides "Powered by ORQO" */
}

For granular control, the widget exposes ::part() selectors: panel, header, messages, input-area, launcher, message-user, message-assistant.

Mobile Behavior

In floating mode, the widget automatically goes full-screen on viewports 480px and below. The launcher button hides when the chat panel is open. Input fields use 16px font size to prevent iOS Safari auto-zoom.

JSON API

For custom integrations, use the REST API directly.

Send a Message

POST /api/v1/chatbot/:token/messages
Content-Type: application/json

{
  "message": "What do you know about X?",
  "visitor_id": "optional-session-id"
}

Response

{
  "conversation_id": 42,
  "visitor_id": "abc-123-def",
  "response": "Based on the knowledge base, here's what I found..."
}

Session Continuity

The visitor_id field maintains conversation context across requests. Same visitor_id = same conversation. If omitted, a new ID is generated and returned — store it client-side to continue the conversation in subsequent requests.

What the Chatbot Can Do

The chatbot has access to five tools, all scoped to the project:

Tool	What it does
Query Knowledge	Search, inspect, and navigate the project's knowledge graph
Remember	Store new insights back into the project's knowledge graph
Web Search	Search the web for supplementary information
Web Fetch	Fetch and extract content from URLs
Read Document	Read documents from the project's document library

What It Cannot Do

Unlike Doorkeeper, the Public Chatbot cannot:

• Access other projects in your organization
• Trigger or manage workflows
• Create or modify projects, documents, or contacts
• Access agent teams or configurations
• Stream responses in real-time (responses are synchronous)

CORS

The API includes permissive CORS headers (Access-Control-Allow-Origin: *), so the widget and custom integrations work from any domain without proxy configuration.

Security

• Project-scoped — The chatbot can only query the knowledge graph of the project it belongs to. No cross-project or organization-wide access.
• Token-based — Each project gets a unique token. Disable the chatbot toggle to immediately revoke access.
• Anonymous — No user accounts or login required for visitors. Conversations are tracked by visitor_id for session continuity only.
• Read-focused — The chatbot can query and navigate knowledge but has no access to administrative functions.

Rate Limiting

The chatbot API enforces per-IP rate limits to prevent abuse:

Limit	Threshold	Window
Burst	10 requests	1 minute
Daily	200 requests	24 hours

Requests that exceed either limit receive a 429 Too Many Requests response with a JSON error message. Limits reset automatically.

Message Validation

• Messages are required — empty requests are rejected.
• Maximum message length is 2,000 characters. Longer messages receive a 422 Unprocessable Entity response.