Skip to main content

​
Chat Sessions

Chat sessions provide conversation context for asking questions about your documents.

​
What are Chat Sessions?

Chat sessions are conversation contexts linked to a folder:
  • Each chat is connected to one folder
  • Maintains conversation history for follow-up questions
  • Multiple chats can be created per folder
  • Isolates different conversation topics or users
Think of chats as conversation threads - each one remembers previous questions and answers within that thread.

​
Core Operations

​
Create a Chat

from cerevox import Hippo

hippo = Hippo(api_key="your-api-key")

# Create chat linked to a folder
chat = hippo.create_chat(
    folder_id="folder_123",
    chat_name="Technical Support Q&A"
)

print(f"Created: {chat.name}")
print(f"Chat ID: {chat.id}")
Response fields:
  • id: Unique chat identifier
  • name: Chat name
  • folder_id: Associated folder
  • created_at: Creation timestamp
  • message_count: Number of Q&A exchanges

​
List Chats

# Get all chats for a folder
chats = hippo.get_chats(folder_id="folder_123")

for chat in chats:
    print(f"{chat.name}: {chat.message_count} messages")

​
Get Chat Details

# Get specific chat information
chat = hippo.get_chat(chat_id="chat_456")

print(f"Name: {chat.name}")
print(f"Folder: {chat.folder_id}")
print(f"Messages: {chat.message_count}")
print(f"Created: {chat.created_at}")

​
Update Chat Name

# Rename a chat
updated_chat = hippo.update_chat(
    chat_id=chat.id,
    chat_name="Customer Support - Priority"
)

print(f"Renamed to: {updated_chat.name}")

​
Delete Chat

# Delete chat and its Q&A history
hippo.delete_chat(chat_id="chat_456")

print("Chat deleted successfully")
Deleting a chat removes all Q&A history. The folder and files remain intact.

​
Chat Organization Patterns

Create individual chats for each user:
# Create chat for each customer
customer_chat = hippo.create_chat(
    folder_id=support_docs_folder.id,
    chat_name=f"Support - Customer {customer_id}"
)
Benefit: Personalized conversation history per user
Organize by conversation topic:
topics = ["Authentication", "Billing", "API Usage", "Troubleshooting"]

chats = {}
for topic in topics:
    chat = hippo.create_chat(folder.id, f"Support - {topic}")
    chats[topic] = chat
Benefit: Clear separation of conversation topics
Create temporary chats for sessions:
# Create chat for this user session
session_chat = hippo.create_chat(
    folder.id,
    f"Session {session_id} - {datetime.now()}"
)

# ... ask questions ...

# Clean up after session ends
hippo.delete_chat(session_chat.id)
Benefit: Automatic cleanup of temporary conversations
Chats for different teams accessing same docs:
departments = ["Sales", "Support", "Engineering"]

for dept in departments:
    chat = hippo.create_chat(
        product_docs_folder.id,
        f"{dept} Team Chat"
    )
Benefit: Department-specific conversation tracking

​
Conversation Context

Chat sessions maintain context for follow-up questions: 
# First question
answer1 = hippo.submit_ask(
    chat.id,
    "What is the API rate limit?"
)
# Answer: "The API rate limit is 1000 requests per hour..."

# Follow-up question (chat remembers previous context)
answer2 = hippo.submit_ask(
    chat.id,
    "How can I increase it?"  # "it" refers to rate limit from Q1
)
# Answer: "To increase your rate limit, contact support..."

# Another follow-up
answer3 = hippo.submit_ask(
    chat.id,
    "What's the process for that?"  # "that" refers to Q2
)
# Answer: "The process for increasing rate limits is..."
Context window: Chats remember the last 10 Q&A exchanges for context.

​
View Chat History

Get all questions and answers from a chat: 
# Get full Q&A history
asks = hippo.get_asks(chat_id=chat.id)

print(f"Chat history ({len(asks)} Q&A):\n")

for i, ask in enumerate(asks, 1):
    print(f"{i}. Q: {ask.question}")
    print(f"   A: {ask.response}")
    print(f"   Sources: {len(ask.sources)}\n")

​
Complete Example: Multi-User Support System

from cerevox import Hippo

hippo = Hippo(api_key="your-api-key")

# 1. Create knowledge base
support_folder = hippo.create_folder(
    "Customer Support Docs",
    "FAQs, troubleshooting, and product guides"
)

# 2. Upload support documents
docs = [
    "faq.pdf",
    "troubleshooting-guide.pdf",
    "product-manual.pdf"
]

for doc in docs:
    hippo.upload_file(support_folder.id, doc)

# 3. Create chats for different purposes
chats = {}

# General support chat
chats['general'] = hippo.create_chat(
    support_folder.id,
    "General Support"
)

# Technical support chat
chats['technical'] = hippo.create_chat(
    support_folder.id,
    "Technical Support"
)

# Billing inquiries chat
chats['billing'] = hippo.create_chat(
    support_folder.id,
    "Billing Support"
)

# 4. Route questions to appropriate chat
def ask_support(question, category='general'):
    chat_id = chats[category].id

    answer = hippo.submit_ask(chat_id, question)

    print(f"Category: {category}")
    print(f"Q: {question}")
    print(f"A: {answer.response}\n")

# Use the system
ask_support("How do I reset my password?", "general")
ask_support("Why is the API returning 500 errors?", "technical")
ask_support("How do I update my payment method?", "billing")

​
Best Practices

Good: “Customer Support - Authentication Issues” Bad: “Chat 1”, “Test”, “Untitled”Clear names help identify chats when you have many.
# Delete old or test chats
chats = hippo.get_chats(folder_id)

for chat in chats:
    if "test" in chat.name.lower() or chat.message_count == 0:
        hippo.delete_chat(chat.id)
        print(f"Deleted: {chat.name}")
Keep your workspace organized by removing unused chats.
Don’t share chats across users:
# Bad: Shared chat for all users
shared_chat = hippo.create_chat(folder.id, "Everyone")

# Good: Individual chats per user
user_chat = hippo.create_chat(
    folder.id,
    f"User {user_id}"
)
Individual chats prevent context confusion and protect privacy.
Temporary chats (delete after session):
chat = hippo.create_chat(folder.id, f"Session {session_id}")
# ... use chat ...
hippo.delete_chat(chat.id)
Permanent chats (keep for history):
chat = hippo.create_chat(folder.id, f"Customer {customer_id}")
# Keep for entire customer relationship

​
Limits & Quotas

Chats per Folder

Free tier: Up to 50 chats Pro tier: Up to 1,000 chats Enterprise: Unlimited

Messages per Chat

All tiers: Unlimited Q&A exchanges Context window: Last 10 exchanges used for context

​
Next Steps

Q&A System

Ask questions in your chats

Best Practices

Optimize chat organization

Examples

Complete RAG workflow examples
⌘I