> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iblueprint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Chatbots

This documentation explains how to build and manage chatbots using the **iBlueprint.ai** platform. It walks through the entire workflow—from setting up a new chatbot to linking knowledge bases, configuring API calls and customizing the chat widget for deployment.

## 1. Accessing the Chatbots workspace

1. **Sign in** to your iBlueprint.ai workspace.
2. Choose **Chatbots** from the left‑hand navigation. The Chatbots page lists existing bots, along with a dashboard summarizing total bots, active bots and sessions. To start a new bot, click **New Chatbot**.

### New chatbot form

On the **Create New Chatbot** page you must supply basic information about your bot. The form includes:

* **Chatbot Name** – required display name for the bot.
* **Description** – optional text explaining the bot’s purpose.
* **Visibility** – choose who can see and edit the bot. Options include *Private* (only you), *Organization* (members of your organization) and *Public*.
* **Tags** – optional keywords to help organize bots in search and dashboards.

A note explains that prompts, knowledge bases and endpoints can be configured after the bot is created. Fill in the fields and click **Create Chatbot** to finish.

## 2. Managing a chatbot

After creation, you are redirected to the **Manage** page, where all aspects of the bot can be configured. Tabs along the top include **Overview**, **Manage**, **Knowledge**, **API Sources**, **Configure**, **Deployments**, **Test Scenarios** and **Logs**.

### 2.1 Settings (Manage tab)

Under the **Manage** tab you can edit core settings:

* **Chatbot Name, Description and Slug** – update these fields as needed. The slug is a URL‑friendly identifier.
* **Status** – set to *Active* or *Inactive* to control whether automations can invoke the bot.
* **Visibility** – adjust who can view or edit the bot (Private, Organization or Public).
* **AI Connection** – choose the large‑language‑model backend. The connection drop‑down lists available AI providers; click **Add New Connection** to configure another provider.
* **Save changes** – click to persist edits.

### 2.2 System Prompt Configuration

The **System Prompt Configuration** section lets you design the base prompt architecture that governs bot behaviour across all deployments. Prompts are assembled from **blocks**:

* **Block Type** – choose *System*, *User* or *Assistant*. The system block defines the overall instructions; user/assistant blocks can supply example interactions.
* **Placement** – choose whether the block appears at the **Start (Before RAG/API)** or **End (After RAG/API)** relative to retrieval‑augmented generation (RAG) results.
* **Prompt Source** – select a prompt from the library or create your own. The selected prompt’s content is inserted into the block, and you can override the text directly.
* **Add Block** – click **Add Block** to insert additional blocks. Blocks can be reordered by dragging the handle.

This structured architecture allows you to combine start prompts, RAG search results, API data and metadata prompts before ending prompts to achieve consistent, configurable behaviour.

## 3. Linking Knowledge Bases (Knowledge tab)

To enable retrieval‑augmented generation, link one or more **knowledge bases** to your chatbot:

1. Open the **Knowledge** tab.
2. The **Linked Knowledge Bases** section displays existing links and a **Link Knowledge Base** button. Click this button to select a knowledge base from your workspace.
3. Each linked knowledge base card shows:
   * **Chunking method** (Auto, Hybrid or Structured), **Max chunks** and **Similarity threshold** (minimum similarity score).
   * A toggle to **Enable** or disable the knowledge base and a **Priority** field to control the order in which bases are searched.
   * **Document Sets** – expand **All Document Sets** to choose specific document collections or use all documents within the knowledge base.
   * **RAG Settings** – fine‑tune retrieval. Options include similarity threshold, max chunks per query, cache TTL, whether to **Include Full Documents**, and the **Retrieval Method**. Retrieval methods include *Hybrid (Both)*, *Structured First* or *Unstructured First*, with a fallback threshold to switch methods if few results are returned.
4. Set the **Enabled** toggle and priority for each base, then save. Higher priority bases are searched first during RAG.

## 4. Configuring External APIs (API Sources tab)

Chatbots can call external APIs before generating a response. In the **API Sources** tab, click **Add API Source** to open the configuration dialog. Provide:

* **Display Name** and **Template Key** – the template key is used to reference the API output in prompts (`{{api_data.template_key}}`).
* **Base URL**, **Endpoint Path** and **HTTP Method** – the path supports variable placeholders using `{{metadata.key}}` syntax (e.g., `/users/{{metadata.user_id}}`).
* **Authentication** – choose *None*, *Basic* or *Bearer* and provide credentials.
* **Request Headers** and **Query Parameters** – JSON objects for custom headers or query strings.
* **Response Mapping (JSON)** – extract nested fields from the API response using JSONPath (e.g., `$.data.user.name`).
* **Timeout**, **Retry attempts** and **Cache TTL** – control network reliability and caching.
* **Webhook Configuration (optional)** – send API responses to a webhook URL and specify a response schema.
* **Enabled** – enable or disable the source. Click **Create API Source** to save.

API data will be injected into the system prompt where the corresponding `{{api_data.template_key}}` placeholder is used.

## 5. Customizing the Chat Experience (Configure tab)

The **Configure** tab allows you to design how the chatbot will appear on a web page and how it interacts with users:

### Display and Chat behaviour

* **Display Mode** – choose *Inline Chat* (embedded inside a container) or *Floating Chat* (a floating button that opens a chat window).
* **Chat Title** – sets the heading displayed at the top of the chat widget.
* **Enable Streaming** – toggle server‑sent events for real‑time streaming responses. If disabled, responses appear after generation completes.
* **Export Tools** – toggle copy‑to‑clipboard and PDF/print buttons.
* **Privacy Agreement** – require users to accept a privacy policy before chatting and supply the policy URL.
* **File Upload** – allow users to attach files with messages (enabled for some deployments).
* **Authorization Token** – enter a bearer token to restrict access to authorized users.

### Theme and Branding

Customize every colour of the chat widget via the **Theme Customization** section:

* Primary and secondary colours, banner colours, hover colours, chat background, user and bot message colours and fonts.
* Font family and optional logo URL.
* Reset to default if needed.

### Layout and Messages

* **Chat Widget Dimensions** – set width and height using CSS values (e.g., `100%`, `500px`).
* **Legal Disclaimer** – text displayed under the chat window to warn users of AI limitations.
* **Initial Welcome Message** – Markdown‑formatted greeting shown when the chat first loads. Use lists, bold or italics for emphasis.
* **Starter Prompt Buttons** – quick‑reply suggestions displayed as pill buttons below the welcome message. They disappear after the first message and reappear when the chat is cleared.
* **Metadata Config** – build metadata fields (e.g., `user_id`, `prompt_ids`, `document_set_ids`) that are passed into prompts. Use **Add Prompt from Library** or **Add Document Set** to include specific prompts or document sets in the metadata.

### Preview and Deployment

A real‑time **Chat Preview** appears below your configuration so you can test the bot’s responses. When ready, click **Save as Deployment** to save the current settings as a named deployment (e.g., “Test v.3”). Deployment configurations can be loaded later from the **Deployments** tab.

## 6. Managing Deployments (Deployments tab)

Deployments capture specific configurations (prompt blocks, knowledge bases, UI settings, metadata). Under the **Deployments** tab you can:

* View a table of saved deployments with names, statuses and creation times.
* **Load** a deployment to restore its settings to the test/chat configuration page.
* **Permissions** – define **Allowed Origins** for cross‑origin requests. Add domains to restrict where your chatbot can be embedded. Use `*` during development to allow all origins.
* **Integration Code Snippet** – copy HTML, React or WordPress snippets to embed the chatbot on your site. The snippet includes your bot’s `chatId`, endpoint URL, theme colours, and metadata.

## 7. Testing and Logs

* **Test Scenarios** – create test cases composed of one or more questions. You can link a test scenario to a specific deployment and run it to verify responses. Results can be viewed from this tab.
* **Logs** – review conversation logs from the bot’s sessions. Logs provide insights into how users interact with your bot; you may need proper permissions to view them.