Skip to content

Chatbot Setup

The Portal Chatbot enables users to explore page data using natural language questions. It is powered by a large language model (LLM) and has access to the data displayed on the current Portal page.

Prerequisites

  • Portal version 1.18.0 or later
  • An API key from a supported LLM provider (see below)
  • The chatbot service deployed alongside the Portal (included in standard Docker deployment)

Supported LLM Providers

Provider Model Examples Required Credentials
Claude (Anthropic) claude-sonnet-4-5-20250929 Anthropic API Key
OpenAI gpt-4 OpenAI API Key
AWS Bedrock us.anthropic.claude-3-5-sonnet-20241022-v2:0 AWS Access Key ID, Secret Access Key, Region

Step 1: Create an LLM Connection

  1. Navigate to Admin Console > Chatbot.
  2. Click Add Connection.
  3. Fill in the connection form:
  4. Connection Name - A descriptive name (e.g., "Claude Production").
  5. Provider - Select Claude, OpenAI, or Bedrock.
  6. Model - Enter the model identifier (or ARN for Bedrock).
  7. Credentials - Enter the API key or access keys for the selected provider. For Bedrock, also specify the AWS Region.
  8. Click Save.

You can create multiple connections for different providers or models.

Warning

API keys are stored securely and are not displayed after saving. To update a key, you must re-enter it.

Step 2: Add a Chatbot Block to a Page

  1. Open a page in edit mode.
  2. Add a new block and select the Chatbot block type.
  3. In the block editor sidebar, select the LLM Connection from the dropdown.
  4. Save the page.

The chatbot is now ready for use on that page.

Step 3: Configure the Chatbot (Optional)

The block editor provides several optional configuration sections:

System Prompt

Customize the chatbot's behavior:

  • Base Prompt - Provide a full system prompt to guide the chatbot's responses.
  • Persona - Configure the chatbot's name, tone (e.g., "professional but approachable"), verbosity (e.g., "concise"), and personality traits.
  • Response Guidelines - Add rules the chatbot should follow (e.g., "Always include the data source in your answer").
  • Few-Shot Examples - Provide example user/assistant message pairs to demonstrate the desired response style.

Guardrails

Control what the chatbot can and cannot do:

  • Topic Restrictions - Block specific topics with a custom redirect message.
  • Data Restrictions - Specify fields that should never be exposed, and set aggregation thresholds.
  • Behavioral Restrictions - Define "never do" and "always do" rules.
  • Rate Limits - Set maximum questions per minute and per session.
  • Output Validation - Require data attribution, enable PII detection (with redact or block actions).
  • Input Validation - Set maximum question length and reject patterns (regex).

UI Settings

  • Welcome Message - Shown when a new chat session starts.
  • Placeholder Text - Shown in the input field before the user types.
  • Avatar Label - The character displayed in the assistant's avatar bubble.

Developer Settings

  • Debug Mode - When enabled, each response shows request ID, token usage (input/output), response latency, cost, and 24-hour token usage.

How the Chatbot Works

  • A chat session is created per block, per page. Sessions timeout after 60 minutes of inactivity.
  • The chatbot automatically receives the current page context, including which blocks and data sources are on the page.
  • Active page filters are sent with each message, so the chatbot's answers reflect the currently filtered data.
  • Users type questions in the input field and press Enter to send. Assistant responses support markdown formatting.

Managing Connections

To edit or delete an LLM connection:

  1. Navigate to Admin Console > Chatbot.
  2. Click the actions menu on the connection you want to modify.
  3. Select Edit or Delete.

Warning

Deleting a connection will cause any chatbot blocks using that connection to stop working.