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

# Connect Your Chatbot

> How to connect your application to Snowglobe for simulation testing.

All work simulations in Snowglobe require an active connection to the chatbot you want to simulate. There are two ways to connect your chatbot to Snowglobe:

1. Connect Snowglobe to an API endpoint that your chatbot is running on. This is the easiest way to get started.
2. Start a local process that wraps your chatbot, and connect Snowglobe to that process. This is more flexible, and allows you to use Snowglobe with any chatbot that can be run as a local process.

<Tip>If you use [Claude Code](https://docs.claude.com/claude-code), the [`snowglobe-skills`](/snowglobe/docs/guide/bootstrap-with-claude-code) plugin runs the entire local-process connection flow for you — install, auth, scaffold, register, test, and start — from a single prompt.</Tip>

## Choose Your Connection Method

|              | API Endpoint via Web UI                               | Connector Library                                          |
| ------------ | ----------------------------------------------------- | ---------------------------------------------------------- |
| **Best for** | Product managers, business users, non-technical teams | Developers, technical teams                                |
| **Pros**     | No coding required, quick setup, visual interface     | Maximum flexibility, full customization, local development |
| **Cons**     | Less customization options                            | Requires technical knowledge, more setup time              |

## Chatbot Configuration

*These steps apply to both connection methods.*

#### Chatbot Name Guidelines

* Use clear, descriptive names (15-50 characters)
* Avoid technical jargon
* Examples: "Customer Support Assistant", "Code Review Bot", "Sales Qualifier"

#### Chatbot Description

Your chatbot description helps users understand:

* What your chatbot does
* When to use it
* What to expect

**Good Example:**

> "Helps customers troubleshoot technical issues with our software. Can diagnose problems, suggest solutions, and escalate complex cases to human support."

<Note>For detailed guidance, see our complete [Chatbot Description Best Practices Guide](/snowglobe/docs/guide/chatbot-description).</Note>

<img src="https://mintlify.s3.us-west-1.amazonaws.com/snowglobe/images/chatbot_setup.png" alt="Snowglobe Chatbot Configuration" />

## Method 1: Via API Endpoint

*Perfect for product managers and business users who want a simple, no-code solution.*

### Before You Begin

Before connecting through the web UI, ensure your development team has prepared your chatbot with these requirements:

#### API Connection Requirements

* **HTTPS Endpoint**: Your chatbot must be accessible via a secure HTTPS URL. Have the authentication as well as any parameters or headers that your chatbot requires.
* **OpenAI Chat Format**: Your chatbot must accept and return messages in OpenAI's chat completion format. Learn more about the [OpenAI chat completion format](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models).

#### What You'll Need

* Chatbot endpoint URL (e.g., `https://your-chatbot.com/api/chat`)
* Authentication key/token and any required headers
* Chatbot name and description (see our [chatbot description guide](#chatbot-configuration))

#### System Prompt (optional)

Use the same base system prompt you give your model today—Snowglobe forwards it as-is with every simulation request.

* Leave it blank if your model injects its own prompt or doesn’t need one.
* Keep the text tight; Snowglobe adds the scenario-specific simulation prompt separately.
* Revisit it when your production prompt changes so the connection stays in sync.

<Note>This field is separate from your [Simulation Prompts](/concepts/simulation-prompt); those describe scenarios, while this sets baseline behavior.</Note>

### Step-by-Step Setup

Follow the instructions in the interactive walkthrough below to connect your chatbot to Snowglobe.

<div style={{ position: 'relative', width: '110%', aspectRatio: '4/3', marginBottom: '0' }}>
  <iframe
    src="https://app.supademo.com/embed/cm7a31b4t0pxb11on0ovlpbuf?embed_v=2&utm_source=embed"
    loading="lazy"
    title="Snowglobe Demo"
    allow="clipboard-write"
    frameBorder="0"
    webkitallowfullscreen="true"
    mozallowfullscreen="true"
    allowFullScreen
    style={{ 
  position: 'absolute', 
  top: 0, 
  left: 0, 
  width: '100%', 
  height: '100%',
  border: 'none',
  borderRadius: '0'
}}
  />
</div>

### Success Indicators

<Check>Green connection status indicator when you navigate to the Chatbot page</Check>

## Method 2: Via Connector Library

*Designed for developers who need maximum flexibility and customization.*

### Install & Authenticate the Connector

<Steps>
  <Step title="Install the Connector">
    ```bash theme={null}
    uv pip install snowglobe
    ```
  </Step>

  <Step title="Generate Your Snowglobe API Key">
    Visit [snowglobe.so/app/keys](https://snowglobe.so/app/keys) to generate your API key.
  </Step>

  <Step title="Authenticate the Connector">
    ```bash theme={null}
    snowglobe login
    ```

    When prompted, enter your API key.
  </Step>
</Steps>

### Initialize the Chatbot Connection

The following command establishes a connection to your chatbot and creates the necessary wrapper code.

```bash theme={null}
snowglobe init
```

#### What this command does

1. Prompts you to select a chatbot connection from your Snowglobe web UI (or create a new one)
2. Creates a template file (chatbot\_wrapper.py) with the wrapper code you need to implement
3. Sets up the local workspace for testing and connecting your chatbot

#### What to Expect

**Chatbot Selection**

You'll see a numbered list of your existing chatbot connections:

<Expandable title="Example chatbot selection">
  ```
  Select a chatbot connection:
  1. Customer Support Assistant
  2. Code Review Bot  
  3. Sales Qualifier
  Enter number (or 'new' to create):
  ```
</Expandable>

**Template Creation**

The command creates `chatbot_wrapper.py` with a template you need to fill in:

<Expandable title="Generated template code">
  ```python chatbot_wrapper.py theme={null}
  from snowglobe_connector import CompletionRequest, CompletionFunctionOutputs

  def process_scenario(request: CompletionRequest) -> CompletionFunctionOutputs:
      """
      Process a simulation scenario through your chatbot.
      
      Args:
          request: The scenario with messages and simulation context
          
      Returns:
          Your chatbot's response to the scenario
      """
      
      # TODO: Implement your chatbot logic here
      # Access the conversation: request.messages
      # Each message has: role, content, and optional snowglobe_data
      
      response = "Your chatbot's response goes here"
      
      return CompletionFunctionOutputs(response=response)
  ```
</Expandable>

**Implementation Reference**

<ResponseField name="Input Format" type="CompletionRequest">
  Your function receives a request containing the simulation scenario.

  <Expandable title="CompletionRequest structure">
    ```python theme={null}
    CompletionRequest(
        messages=[
            SnowglobeMessage(
                role="user", 
                content="Help me with this math problem...",
                snowglobe_data=None  # Optional simulation metadata
            )
        ]
    )
    ```
  </Expandable>
</ResponseField>

<ResponseField name="Output Format" type="CompletionFunctionOutputs" required>
  Return your chatbot's response as a structured object.

  <Expandable title="CompletionFunctionOutputs structure">
    ```python theme={null}
    CompletionFunctionOutputs(
      response="Your chatbot's response here"
    )
    ```
  </Expandable>
</ResponseField>

### Test Your Wrapper

Validates your chatbot\_wrapper.py implementation by running a test scenario through your chatbot.

```bash theme={null}
snowglobe test
```

### Connect Your Chatbot

Connects your local chatbot to a specific simulation and processes its scenarios. As of client `1.0.0`, `connect` replaces the previous `start` command and `--simulation-id` is required — create the simulation first (in the [dashboard](https://snowglobe.so/app), or with [`snowglobe simulate`](/snowglobe/docs/connect/launch-a-simulation)) and pass its ID.

```bash theme={null}
snowglobe connect --simulation-id <simulation-id>
```

#### What to Expect

<Expandable title="Example output">
  ```
  Connection successful!
  Your chatbot is now connected to Snowglobe.
  Polling for new scenarios...
  ```
</Expandable>

### Success Indicators

<Check>Green connection status indicator when you navigate to the Chatbot page</Check>
<Check>Command line should show this message: `Connection successful!`</Check>

## Resources

*Need help? Our support team is available to assist with your chatbot integration.*

<CardGroup cols={2}>
  <Card title="Join the Community" icon="users" href="https://discord.gg/U9RKkZSBgx" arrow="true">
    Connect with other developers, ask questions, and share feedback.
  </Card>

  <Card title="See Examples" icon="cubes" href="/snowglobe/docs/examples/llm" arrow="true">
    See examples and showcase of various chatbots simulated with Snowglobe.
  </Card>

  <Card title="Write Chatbot Description" icon="square-check" href="/snowglobe/docs/guide/write-chatbot-description" arrow="true">
    Learn best practices for writing effective chatbot descriptions.
  </Card>

  <Card title="Define Simulation Prompt" icon="bullseye-arrow" href="/snowglobe/docs/guide/define-sim-intent" arrow="true">
    Learn how to define what you want to test with your simulations.
  </Card>
</CardGroup>