> ## 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.

# Build a chatbot: every step and tab

> A walkthrough of the iBlueprint chatbot builder — from the initial create flow through every tab in the chatbot settings (Widget, Embed, Security, Data capture, Sessions).

iBlueprint turns any Blueprint into a live chat interface you can embed on your website. This page walks through the full builder — the initial create dialog and every tab in the chatbot settings — in the order you will use them.

## Before you start

You need:

* A published [Blueprint](/blueprints/overview) that accepts a single text input (the visitor's message) and returns a single text output (the reply).
* An AI provider connection configured under [Integrations → AI providers](/integrations/ai-providers).
* The domain(s) where you plan to embed the widget.

## Step 1: Create the chatbot

<Steps>
  <Step title="Open Chatbots">
    From the left navigation, go to **Chatbots** and click **New chatbot**.
  </Step>

  <Step title="Name and describe it">
    * **Name** — 3–120 characters. Shown in the widget header and in your chatbot list.
    * **Description** — optional, up to 1,000 characters. Internal notes for your team.
  </Step>

  <Step title="Connect a Blueprint">
    Pick the Blueprint that will process each incoming message. Every visitor message becomes an input to that Blueprint chain, and the Blueprint's final output is returned as the chatbot's reply.
  </Step>

  <Step title="Choose an AI connection">
    Select the AI provider connection the chatbot should use by default for language model calls. You can use your own API key (BYOK) or a platform-provided connection.
  </Step>

  <Step title="Set visibility">
    * **Private** — only you can see and use the chatbot.
    * **Shared** — accessible to members of your organization.
    * **Public** — accessible to anyone with the embed code or direct link.
  </Step>

  <Step title="Save">
    Click **Create chatbot**. iBlueprint provisions the chatbot and takes you to its settings page, which is organized into the tabs below.
  </Step>
</Steps>

## Step 2: Overview tab

The first tab after creation is **Overview**. Use it to confirm what you just configured and to find quick links you will need later.

* **Status** — live, paused, or draft. Toggle the **Active** switch to take the chatbot offline without deleting it.
* **Chatbot ID** — the identifier you paste into your embed code. Click the copy icon next to it.
* **Direct link** — a hosted URL (`https://chat.iblueprint.io/c/YOUR_CHATBOT_ID`) you can share without embedding.
* **Connected Blueprint** — click to jump straight into the Blueprint editor.
* **Recent activity** — last 24 hours of messages, error rate, and average response time.

## Step 3: Widget tab

The Widget tab controls how the chatbot looks and behaves in the floating widget.

### Branding and style

| Field                        | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| Header title                 | Name shown at the top of the chat widget.                 |
| Welcome message              | First message visitors see when the chat opens.           |
| Placeholder text             | Hint text shown inside the message input field.           |
| Primary color                | Accent color for buttons and highlights (hex code).       |
| Logo URL                     | Brand logo, displayed in the widget header.               |
| Position                     | Anchor the widget to **bottom-right** or **bottom-left**. |
| Show "Powered by iBlueprint" | Toggle the iBlueprint attribution badge on or off.        |

### Behavior

* **Open on load** — open the widget automatically when the page loads instead of waiting for a click.
* **Persist conversations** — keep the conversation history across page navigation in the same session.
* **Typing indicator** — show an animated indicator while the Blueprint is generating a reply.
* **Suggested prompts** — up to four starter prompts shown as clickable chips inside the welcome message.

### Rate limiting

Cap how many messages a single visitor can send to prevent abuse:

* **Max messages per minute**
* **Max messages per hour**
* **Max messages per day**

Visitors who exceed a limit see a friendly message and can resume when the window resets.

## Step 4: Embed tab

The Embed tab gives you the code to drop into your site. There are two options.

### Script (floating widget)

Paste this snippet just before the closing `</body>` tag of any page where the widget should appear:

```html theme={null}
<script
  src="https://cdn.iblueprint.io/widget.js"
  data-chatbot-id="YOUR_CHATBOT_ID"
  async
></script>
```

The script loads asynchronously and renders a floating chat button. Visitors click the button to open the widget.

### iframe (inline panel)

Embed the chatbot as a full-page or panel component:

```html theme={null}
<iframe
  src="https://chat.iblueprint.io/c/YOUR_CHATBOT_ID"
  width="400"
  height="600"
  frameborder="0"
  allow="microphone"
></iframe>
```

Use this option when you want the chat interface inside a specific container on your page rather than as a floating overlay.

<Tip>
  Replace `YOUR_CHATBOT_ID` with the ID shown on the Overview or Embed tab.
</Tip>

## Step 5: Security tab

### CORS rules

By default, iBlueprint restricts which domains can load the chat widget. Add an allowed origin for each domain where you plan to embed the chatbot.

<Steps>
  <Step title="Open CORS settings">
    Go to **Security → CORS rules**.
  </Step>

  <Step title="Add an allowed origin">
    Click **Add origin** and enter the full origin, including the scheme and port if non-standard:

    ```
    https://www.your-company.com
    ```
  </Step>

  <Step title="Save">
    Click **Save**. iBlueprint immediately enforces the new rule for all embed requests.
  </Step>
</Steps>

<Warning>
  Do not use a wildcard (`*`) for public chatbots that handle sensitive data or trigger backend actions. Always restrict origins to the specific domains you control.
</Warning>

### Authentication

For chatbots that should only be accessible to logged-in users:

* **Signed embeds** — generate a short-lived JWT on your backend and pass it to the widget via `data-auth-token`. iBlueprint validates the token against the public key you upload here.
* **IP allowlist** — restrict access to a list of CIDR ranges, useful for internal tools.

### Content filters

Turn on built-in filters to block messages that contain profanity, PII, or prompt-injection patterns before they reach your Blueprint. Each filter logs a blocked event you can review in the Sessions tab.

## Step 6: Data capture tab

Data capture forms collect structured information from visitors during a chat session — for example, a name and email before the conversation starts, or a support ticket category mid-conversation.

<Steps>
  <Step title="Open Data capture">
    Go to the chatbot's **Data capture** tab and click **New form**.
  </Step>

  <Step title="Name the form">
    Give it a descriptive name (for example, **Lead qualification** or **Pre-chat contact info**).
  </Step>

  <Step title="Define the schema">
    Add the fields you want to collect. Each field has:

    * **Name** — the key the value is stored under.
    * **Type** — `string`, `number`, or `boolean`.
    * **Description** — guidance for the AI when it asks for the value.
    * **Required** — whether the conversation can proceed without a value.

    iBlueprint stores this as a JSON schema and uses it to validate responses.
  </Step>

  <Step title="Configure question mode">
    Choose how the chatbot collects the data:

    * **Conversational** — the AI asks one question at a time, in natural language.
    * **Structured** — a form UI is rendered inside the chat with all fields at once.

    Use **question mappings** to control the exact wording the AI uses for each field in conversational mode.
  </Step>

  <Step title="Pick a trigger">
    * **At conversation start** — show the form before the first reply.
    * **Mid-conversation** — fire when a Blueprint node emits a `request_capture` event.
    * **On exit intent** — show the form when the visitor tries to close the widget.
  </Step>

  <Step title="Activate the form">
    Toggle the form **Active**. iBlueprint begins presenting it to new visitors according to your configuration.
  </Step>
</Steps>

Captured responses are stored as sessions (see the Sessions tab below) and can be passed into downstream Blueprint nodes for further processing.

## Step 7: Sessions tab

The Sessions tab is your log of every conversation the chatbot has had.

Each session row shows:

* Session ID and start time
* Visitor identifier (IP-derived by default, or your `data-user-id` if signed embeds are configured)
* Message count and total token usage
* Captured form data (if any)
* Final status — completed, abandoned, blocked, or errored

Click any session to see the full transcript, the Blueprint execution log for each turn, and any captured data. From the detail view you can:

* **Export** the transcript as JSON or CSV.
* **Replay** the conversation against a different Blueprint version to test changes.
* **Flag** the session for review — flagged sessions are surfaced on the Overview tab.

## Step 8: Analytics tab

The Analytics tab summarizes chatbot performance over a date range you pick.

* **Volume** — messages, sessions, and unique visitors per day.
* **Latency** — average and p95 response time, broken down by Blueprint node.
* **Cost** — token spend by model and by node.
* **Containment** — percentage of sessions that ended without being escalated (handoff node fired).
* **Feedback** — thumbs-up / thumbs-down ratings visitors leave on individual replies.

Export any chart as a CSV or pin it to a workspace dashboard.

## Step 9: Versions tab

Every change you save to the chatbot's settings creates a new version, mirroring how Blueprint and prompt versions work.

* **Diff** any two versions to see what changed.
* **Restore** a previous version — the restore itself is recorded as a new version, so history is never rewritten.
* **Pin** a version as the live one. Until you pin, the latest saved version is the live one.

See [Versioning](/blueprints/versioning) for the underlying model.

## Step 10: Test and go live

Before you embed:

1. Open the chatbot's **direct link** from the Overview tab and run through a real conversation.
2. Check the **Sessions** tab to confirm the transcript and any captured data look correct.
3. Watch the **Analytics** tab during your first day in production — keep an eye on the error rate and p95 latency.

When everything looks right, paste the embed code from Step 4 onto your site and confirm the origin is allowlisted in Step 5.