Chatbot

Classic chatbot with RAG over your data — no supervisor or sub-agents

The Chatbot service is the classic chatbot: no supervisor or sub-agents. You create a collection (knowledge base from URLs, documents, or text); that collection is registered and stored for you. Then you create chatbots linked to that collection and give each one instructions (system prompt). You open conversation sessions with those chatbots. In each session, user questions are matched against the collection using RAG; we retrieve the relevant chunks. When the question fits your rules, an LLM generates the answer and we return it via REST or SSE streaming. One collection, one or more chatbots, many sessions — simple and predictable.

chatragllm

Overview

Features

Create collections from your data

Create a collection from URLs (web pages) or document uploads. It is stored and indexed for RAG so chatbots can query it.

Chatbots linked to collections + instructions

Create chatbots tied to one or more collections. Set system_message (instructions) per chatbot to define behavior, tone, and boundaries.

Conversation sessions

Each chat call opens or continues a conversation. Pass conversation_id to continue an existing thread; omit it for a new conversation. List, inspect, or delete sessions.

RAG + LLM, REST or SSE

Questions are grounded in the collection via RAG; retrieved sources are returned in enhanced_analysis. The LLM answers and you get the response in one shot (REST) or as a stream (SSE, set stream:true).

Use Cases

Customer support bot

Build a collection from help center / FAQ; create a chatbot with support instructions; open conversation sessions per user. Answers are grounded in your docs via RAG, returned as REST or SSE.

Internal knowledge base

Index company docs and SOPs in a collection; chatbots with clear system_message serve employees. Sessions keep context; RAG + LLM answers within your rules.

Product or e-commerce assistant

Collection from product catalogs and reviews; chatbots linked to it. Sessions per user; RAG retrieves relevant items; LLM answers.

Education or onboarding

Course or onboarding content in a collection; chatbots with instructions and sessions. Questions answered from the collection within your rules.

Input / Output

Input

Collection sources (URLs or documents), chatbot configuration (system_message, temperature, model), conversation_id, and chat messages

JSON bodyURL or document references (for collections)

Output

LLM-generated response grounded in collection via RAG, with enhanced_analysis (relevance scores, sources); REST or SSE

JSONSSE stream (stream:true)

Specs

Latency: ~1-3s first token (REST), streaming starts in ~500ms (SSE)
Async: false
Rate Limit: 60 req/min per API key
Max Input: Per chatbot model context_window; messages typically fit in a few thousand tokens

Quickstart

Prerequisites

-A CN8 Gateway API key with chatbot services enabled
-At least one data source (URL, text, or document) to build a collection

1. Create a Knowledge Collection

core-collection-create

Create a collection from your sources. Indexing runs so chatbots can query it for RAG.

POST/v1/proxy/core-collection-create

{
  "name": "support-docs",
  "source_type": "web_pages",
  "sources": [
    { "page_url": "https://docs.example.com/faq", "title": "FAQ" }
  ]
}

Response

{
  "status": "success",
  "data": {
    "collection_id": "cl_abc123",
    "collection_name": "support-docs",
    "status": "ready",
    "source_types": ["web_pages"],
    "data_sources": [
      { "id": "ds-uuid", "name": "FAQ", "source_type": "web_pages" }
    ]
  }
}

Use the returned collection_id (cl_ prefix) in subsequent calls. Status begins as 'indexing' and becomes 'ready'.

2. Create a Chatbot

core-chatbot-create

Create a chatbot linked to one or more collections. Set system_message (instructions) and temperature to control behavior.

POST/v1/proxy/core-chatbot-create

{
  "name": "Support Bot",
  "collection_ids": ["cl_abc123"],
  "system_message": "You are a helpful customer support agent. Answer questions using the provided knowledge base. If you don't know the answer, say so honestly.",
  "temperature": 0.3
}

Response

{
  "status": "success",
  "data": {
    "chatbot_key": "cb_xyz789",
    "name": "Support Bot",
    "system_message": "You are a helpful customer support agent...",
    "temperature": 0.3,
    "collection_ids": ["cl_abc123"],
    "created_at": "2026-04-27T10:30:00Z"
  }
}

Use chatbot_key (cb_ prefix) in subsequent calls. Lower temperature (0.1-0.3) gives more factual answers; higher (0.7-1.0) is more creative.

3. Send a Message (REST)

core-chat

Send a message; the chatbot retrieves context from its collections via RAG and generates a response. NOTE: request uses 'chatbot_id' as field name, not 'chatbot_key' — the value is still the cb_ key returned by create.

POST/v1/proxy/core-chat

{
  "chatbot_id": "cb_xyz789",
  "message": "What is your refund policy?"
}

Response

{
  "status": "success",
  "data": {
    "conversation_key": "cv_def456",
    "response": "Our refund policy allows customers to request a full refund within 30 days...",
    "enhanced_analysis": {
      "source_count": 3,
      "content_types": ["web_pages"],
      "dominant_content_type": "web_pages",
      "scoring_method": "enhanced",
      "is_enhanced": true,
      "relevance_scores": [
        { "content_id": "https://docs.example.com/refunds", "content_type": "web_pages", "relevance_score": 0.78, "match_count": 4, "title": "Refund Policy", "url": "https://docs.example.com/refunds", "source": "https://docs.example.com/refunds", "summary": "", "sections_count": 4 }
      ]
    }
  },
  "gateway": { "request_id": "req_abc", "service": "core-chat" },
  "cost": { "units": 1.0, "unit_price": 0.001, "tokens": 0.001, "balance": 99.99 }
}

Pass the returned conversation_key as conversation_id (or conversation_key) in the next request to continue the same conversation. Field naming inconsistency: chatbot_id (request) vs chatbot_key (response) — use the cb_-prefixed value either way.

4. Stream Responses (Optional)

core-chat

Add stream:true to the same core-chat endpoint. Tokens arrive as Server-Sent Events in OpenAI-compatible format.

POST/v1/proxy/core-chat

{
  "chatbot_id": "cb_xyz789",
  "message": "What is your refund policy?",
  "conversation_id": "cv_def456",
  "stream": true
}

Response

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}],"conversation_key":"cv_def456"}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Our refund"},"finish_reason":null}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" policy allows..."},"finish_reason":null}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":280,"completion_tokens":62,"total_tokens":342}}
data: [DONE]

Pay only for what you use. Listing and management read operations are free.

Service	Unit	Price
Create / Update Collection	item	$1.0/operation
Create Chatbot	item	$1.0/chatbot
Update Chatbot	item	$0.5/update
Chat (REST or SSE)	token	$0.001/call (currently flat — see note below)
List, Get, Delete operations	item	Free

-core-chat is currently billed at a flat 0.001 per call: the upstream chat response does not surface per-call token counts to the gateway, so units defaults to 1.0. To enable token-accurate billing, the upstream needs to populate usage.cost (or usage.total_tokens) like the LLM completions endpoint does.
-Long conversations include previous messages as RAG context — the underlying LLM cost grows with conversation length even if the gateway-billed amount stays flat for now.

Guides & Tips

Optimize Collection Quality

-Keep sources focused: A collection with 10 highly relevant pages will perform better than one with 1000 loosely related pages.
-Update regularly: If your source content changes (e.g., help docs), update the collection to re-embed with fresh data.
-Split by domain: Create separate collections for different topics (e.g., "billing-docs", "product-docs") and assign the right ones to each chatbot via collection_ids.

Choose REST or SSE

-REST (`core-chat`): simplest integration, full response at once. Best for server-to-server, webhooks, or batch workflows.
-SSE (`core-chat` with `stream:true`): tokens arrive as they're generated for a typing-effect UX. Same endpoint, just add `"stream": true`.

System Message Best Practices

-Be specific: "You are a customer support agent for Acme Corp. Answer questions about billing, shipping, and returns." beats "You are helpful."
-Set boundaries: "If the answer is not in the provided context, say 'I don't have that information' instead of guessing."
-Define tone: "Respond in a friendly, professional tone. Use short sentences. Avoid jargon."
-Add constraints: "Keep responses under 150 words unless the user asks for detail."

Field Naming Quirks

-Collection identifier: returned as `collection_id` (cl_ prefix). Use this in details / update / delete and as the value of `collection_ids` when creating or updating a chatbot.
-Chatbot identifier: returned as `chatbot_key` (cb_ prefix). Use as path parameter for chatbot endpoints. The chat endpoint takes it under the request body field `chatbot_id` — same value, different field name. (Inconsistent upstream naming; documenting reality here.)
-Conversation identifier: returned as `conversation_key` (cv_ prefix). Pass back to chat as `conversation_id` (or `conversation_key`) to continue.

FAQ

Q: How many collections can a single chatbot use?

A: Multiple. Pass them in the collection_ids array. The AI searches all connected collections when answering.

Q: What happens when a collection is being re-indexed?

A: The chatbot continues to use the previous version until re-indexing completes. There is no downtime.

Q: Can I use my own OpenAI API key?

A: No, all LLM calls go through the CN8 Gateway. This simplifies billing and ensures consistent behavior.

Q: Why does the request use chatbot_id while the response uses chatbot_key?

A: Upstream naming inconsistency. The value is the same (cb_ prefix); only the field name differs. Documented under Field Naming Quirks.

Q: Why is core-chat billed flat instead of per-token?

A: The chat upstream does not currently report token counts back to the gateway. Until that's added, billing falls back to a flat 1 unit × $0.001. The LLM completions endpoint does report per-call cost via usage.cost; chat will follow once the upstream adds it.

Q: What data formats can I upload to a collection?

A: URLs (web pages are scraped automatically) and document references (uploaded via the data-sources flow). PDF and document upload is supported via source_type='documents'.

Related Products

agent llm text-qa

Changelog

1.1 (2026-04-27)

-Corrected field names to match the actual upstream: collection_key → collection_id, name → collection_name, system_prompt → system_message, collection_keys → collection_ids.
-core-collections / core-chatbots: data is a direct array, not data.collections / data.chatbots. Added pagination object to all list responses.
-core-conversations: documented the required chatbot_id parameter (path or query) and the 400 error when omitted.
-core-chat: request field is chatbot_id (not chatbot_key) — same cb_-prefixed value, different field name. Response uses data.response (not data.answer) and data.enhanced_analysis (richer than the previous 'sources' field). Documented the current flat 0.001/call billing behaviour.
-core-collection-details: documented that the response is sparse (only collection_id, source_types, data_sources) — no name/description/created_at/status/chunk_count.
-core-chatbot-details: added statistics and public_domains fields that the upstream returns.
-Added Field Naming Quirks guide and FAQ entries explaining the chatbot_id/chatbot_key inconsistency and the chat billing behaviour.

1.0 (2026-01-01)

-Initial release with collection CRUD, chatbot CRUD, chat (REST/SSE), conversation management.