Connect Your Chatbot

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.

​

Choose Your Connection Method

​

Chatbot Configuration

​

Chatbot Name Guidelines

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

​

Chatbot Description

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

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

​

Method 1: Via API Endpoint

​

Before You Begin

​

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.

​

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)

​

System Prompt (optional)

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

​

Step-by-Step Setup

​

Success Indicators

​

Method 2: Via Connector Library

​

Install & Authenticate the Connector

uv pip install snowglobe

snowglobe-connect auth

​

Initialize the Chatbot Connection

snowglobe-connect 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

Select a chatbot connection:
1. Customer Support Assistant
2. Code Review Bot  
3. Sales Qualifier
Enter number (or 'new' to create):

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)

CompletionRequest(
    messages=[
        SnowglobeMessage(
            role="user", 
            content="Help me with this math problem...",
            snowglobe_data=None  # Optional simulation metadata
        )
    ]
)

CompletionFunctionOutputs(
  response="Your chatbot's response here"
)

​

Test Your Wrapper

snowglobe-connect test

​

Connect Your Chatbot

snowglobe-connect connect

​

What to Expect

Connection successful!
Your chatbot is now connected to Snowglobe.
Polling for new scenarios...

​

Success Indicators

​

Resources