How Objx Works

Create agents from the app: go to New Agent and choose a blank agent, a template (e.g. SimpleLoop, OB1 Clone, Customer Service), or import from JSON. Each agent has a name and optional description. After creation, open the agent to configure flows, knowledge bases, and options.

On the agent page, use the General tab and the Settings card to configure:

• Main Features: Realtime Voice (allow starting a real-time voice call in chat; must be on to use Twilio Voice), allow audio transcription (Whisper), file uploads, user model selection, image generation
• ObjxChat display: Show voting, costs, model name, profile icon; input prompt size (small/large); image-only mode; task drawer
• Models: Available models and default model (when user selection is allowed)
• Twilio Voice (SIP): Enable incoming phone calls via OpenAI SIP; requires Realtime Voice to be enabled in Main Features. Configure webhook URL and secret in platform.openai.com.

Agent context (system context), welcome message, suggestions, and visibility (public, shared, published) are also set on the agent. Save changes with the header Save button.

From the agent's General tab, open Flows and create or edit a flow. The Flow Board is a canvas where you add nodes and connect them. Execution starts at the Start node. Use the inspector panel when a node is selected to edit its content and options.

Flow node types

• Start — Entry point (auto-created)
• Message — Output text/markdown to the user; supports variables like ${lastInput}, ${lastResponse}
• Image — Display an image in chat
• Prompt — Wait for user input; stores response in a variable (e.g. lastInput)
• Model — Call an LLM with system message, temperature, model; optional tools (e.g. KB search, route thread, update capture fields)
• Knowledgebase (Database) — Vector search over a knowledge base; query can use variables
• Intent Database — Search intent phrases across flows for routing
• Goto Flow — Jump to another flow by name
• Switch — Branch by regex, cosine similarity, or LLM
• Phrase — Branch destination with optional flow navigation
• Branch — Tool-based branch destination
• Agent Memory — GET/PUT/APPEND agent memory by key
• Avatar — Control avatar (toyHead) behavior
• Button Switch / Button Branch — Interactive buttons and destinations
• Redirect — Redirect browser to a URL
• Realtime Voice — Speech-to-speech with OpenAI Realtime API
• Update Capture With Schema — Update thread capture fields with a JSON schema
• Update Captured Relationships — Append document relationships to capture fields (e.g. after KB search)

Define flow variables in the flow header (Variables button). Use ${variableName} in node content. Test with the Play button to open a chat sidebar and run the flow.

Knowledge bases hold documents that are chunked and embedded for semantic search. You can use agent-specific knowledge bases (from the agent's Knowledge Bases card) or shared knowledge bases from the app Knowledge Bases page.

Add content as FAQ (Q&A pairs), PDF uploads, or URL (web page). The site processes and indexes the content so your flows can search it. In a flow, add a Knowledgebase (Database) node, select the knowledge base, and set the search query (e.g. ${lastInput}). The node outputs relevant chunks for use in later nodes (e.g. passed into a Model node as context). You can also attach a KB Tool to a Model node so the LLM can search the knowledge base via a tool call.

Show Document tool

The Show Document tool lets the LLM display a knowledge base document in the chat as a card. The card shows the document title, a truncated description, a thumbnail (if the document has a blob), contact details (phone, email, website, social links) as badges, and its relationships to other documents. Clicking the thumbnail opens it in a lightbox; clicking the card opens a focus view; clicking a relationship opens the linked document in a lightbox. Enable it in the flow: select a Model node, open Configure Tools, and turn on Show Document. You can also enable or disable it from the agent's Tools card (Settings).

Document categories

Each knowledge base has a Categories tab where you can define hierarchical document categories (e.g. to organize or filter documents). You can Export all categories to a JSON file (with IDs, parent–child links, and properties) and Import from a JSON file. Import never overwrites existing categories by ID; it only creates new categories for IDs that are not already in the knowledge base. Parent–child relationships are preserved when the parent exists in the KB or is created in the same import.

When editing a document (document detail page), you assign categories via a row of badges (each with a close control to remove) and an Add button next to the Categories label. Clicking Add opens a category picker modal with a search bar, a banner showing the currently selected categories (each with a checkbox to clear it), and a hierarchical outline of all categories with checkboxes. Use OK to apply the selection and close, or Cancel to close without saving changes.

In the main header of a knowledge base page (when on the Documents tab), the List / Card / Graph view switcher controls how documents are displayed. This applies to both the full document list and search results: when you search, the selected view persists and the displayed context becomes the search results. List shows a table; Card shows a grid of document cards; Graph shows an interactive graph of documents and their relationships.

Ingestion modal

When you open a knowledge base from an agent, the header shows a green Ingestion button. Clicking it opens a full-screen ingestion modal with three columns: the agent’s ingestion flow chat (left), the thread’s captured fields JSON (center), and the workboard (right). The ingestion flow is configured in the agent’s Settings (Ingestion flow). The flow can capture documents and document relationships into the thread’s capture fields.

Ingestion Engine (queue)

On the agent knowledge base page, the Ingestion tab can show a Queue column (toggle with the Queue button in the header). When the queue is on, submissions are queued and processed in order. The left column becomes the Ingestion Engine: a title, a short message that submissions are queued and processed in order, an input at the top to add items (text or URL), and a table of threads in the queue. Each row shows a status icon (waiting, processing, review, saved, ready, rejected), a truncated preview of the first message, and—while waiting—a timer counting up from when the item was added. Clicking a row loads that thread’s chat history and captured fields in the middle column and workboard.

The chat area shows Queue mode (a grey placeholder with an engine icon) instead of the normal input; the engine processes the oldest waiting thread automatically when the tab is open. When processing finishes, the thread’s status becomes ready. You can then use Save to persist documents to the knowledge base (Save is disabled while a thread is waiting or processing, or after it is already saved). The blue Review button sets the thread’s status to review; the red Reject button sets it to rejected. After saving, the view resets to a new thread so you can continue with the next item.

The workboard shows a graph of document cards with relationship lines and labels (e.g. references, related_to, parent_of) between them based on document_relationships in the captured fields. Use the layout selector to choose Force (animated force-directed layout) or Masonry (static grid). In Force mode, cards are arranged with a force-directed layout that animates into place over a short period. The largest card (by content size) stays in the center; others arrange around it. Cards repel each other while connected documents attract, balancing into a stable layout. A red border marks the board boundary; cards stay inside it.

Cards are draggable—use the grip handle in the top-right corner of a card to reposition it; positions are kept for the current session. Click a card to edit its content (title, description, URL, type, etc.). Saving an edit updates the captured fields and persists them to the thread.

When the ingestion flow marks a document as an update to an existing record (new version), the modal header shows a flashing warning icon and the card displays a diff of the current workboard version against the version already stored in the knowledge base: additions are highlighted in green, deletions in red (with strikethrough), and any field that changed is visually highlighted. This lets you review changes before saving.

Use the header Save button to persist all documents and document relationships from the workboard into the knowledge base. Existing documents (by ID) are updated; new documents are created. Relationships are written to the knowledge base’s document links. After a successful save, for each new document, a chunk is created from the title and description, and embeddings are generated in the background. The thread’s capture fields are updated with the real document IDs. A popup in the bottom-right corner shows chunking progress (e.g. 2/5 documents). When complete, the modal closes and the documents table refreshes. Document cards can include address (street, city, province, postal code), contact (phone, email, website), and social media (Facebook, Instagram, X, LinkedIn). These fields are editable in the card edit dialog and appear in the card view and document detail page. The searchkb tool returns these fields when querying the knowledge base.

Captured documents can include category IDs (UUIDs of this knowledge base’s document categories). When present, those categories are shown as badges on each document card on the workboard and in the edit document modal. When you save to the knowledge base, document–category relationships are created or updated so the document appears under those categories in the Documents tab.

Prompts are stored content (text, image, sound, video) that users can load into the chat input and send. Create and manage them from the Prompts page. Each prompt has a name, description, content type, and prompt content; you can attach an image and files. When a user loads a prompt in ObjxChat, its content and files are sent as the next message. Prompts can be shared and published for use across the tenant.

You can embed your agent’s chat on your own site so visitors can talk to the agent without leaving the page. Make the agent public in its settings, then use the embed or popup option provided by Objx (e.g. a link or script you add to your site). On WordPress, use the Objx plugin’s shortcode to place the chat widget on any page and optionally set a starting prompt and title. Visitors get a working chat that runs your flows and knowledge bases.

Control how the embedded chat looks (logo, colors, etc.) in the agent’s Popup tab under popup settings.

Each agent can have thread channels (ObjxThreadChannel): named groups (with optional icon and description) used to route and view threads. On the agent's Threads tab (Tickets board), create and edit channels in the first column. Threads can be assigned to at most one channel. In a flow, enable the Route Thread tool on a Model node; the LLM can then call routeThread(toChannel) with a channel ID to move the current thread into that channel. Use Update Capture Fields on the Model node so the LLM can call updateCaptureFields(keysAndValues) to store captured data on the thread. Enable Include Capture Context to append the thread's capture fields to the system prompt. Finish Capture is another tool to signal capture completion. Channels are listed in the Threads tab so you can filter and manage leads by channel.

Open the agent and go to the Threads tab to see all threads for that agent. Threads are grouped by channel, plus Active (not in a channel) and Archive. Use the second column to filter by channel/group and the third to read the selected thread, add admin notes, view capture fields, and update status. The board refreshes on a timer; new threads and new messages can trigger notification sounds. You can search threads and filter by status. From the app sidebar you can also open a global Threads or Inbox view depending on your app routes.