Managing Conversations

Learn to effectively manage, design, and optimize AI conversations for better user experiences.

Chat Sessions

Persistent conversations with full message history and context.

Context & Memory

Maintain coherent, personalized conversations across multiple turns.

Tools & Attachments

Enhance conversations with document processing and built-in tools.

Tip
This guide builds on the concepts from Creating Your First Persona. Make sure you're familiar with persona basics before diving into conversation management.

Conversation Lifecycle

Understanding the conversation lifecycle helps you design better user experiences and implement appropriate management strategies at each stage.

Conversation Stages

1
Session Creation

Create a chat session with a specific persona.

JavaScript
// Create a new chat session
const session = await fetch('/api/trpc/chat.createSession', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Organization-ID': orgId,
  },
  body: JSON.stringify({
    json: {
      personaId: 'clx1abc123xyz789',
      title: 'Customer Support Chat',
      platform: 'API'
    }
  })
});
2
Message Exchange

Send messages and receive AI-generated responses.

JavaScript
// Send a message and get AI response
const response = await fetch('/api/trpc/chat.sendMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Organization-ID': orgId,
  },
  body: JSON.stringify({
    json: {
      chatSessionId: session.id,
      content: 'Hello! I need help with my account.',
      role: 'USER'
    }
  })
});

const { userMessage, aiMessage } = await response.json();
3
Context Building

As the conversation progresses, context is automatically maintained.

  • • Recent messages are included for context (last 10 by default)
  • • Attachments are processed and text is extracted
  • • Persona configuration guides response style
  • • Tools are available for extended capabilities
4
Session Closure

Archive or delete sessions when complete.

JavaScript
// Delete a session when no longer needed
await fetch('/api/trpc/chat.delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Organization-ID': orgId,
  },
  body: JSON.stringify({
    json: { id: session.id }
  })
});

Session Management

Properly managing chat sessions ensures clean resource usage and good user experience.

List All Sessions

Retrieve all chat sessions for the current user, optionally filtered by persona.

JavaScript
// List all sessions
const sessions = await fetch('/api/trpc/chat.sessions?input={}', {
  headers: {
    'X-API-Key': apiKey,
    'X-Organization-ID': orgId,
  }
});

// Filter by persona
const personaSessions = await fetch(
  '/api/trpc/chat.sessions?input=' + 
  encodeURIComponent(JSON.stringify({ personaId: 'clx1abc123xyz789' })),
  {
    headers: {
      'X-API-Key': apiKey,
      'X-Organization-ID': orgId,
    }
  }
);

Managing Context

Effective context management is crucial for maintaining coherent, personalized conversations.

How Context Works in AIPersona

Automatic Context
  • • Recent messages (last 10) are included automatically
  • • Persona system prompt is always included
  • • Persona configuration (temperature, max tokens)
  • • Enabled tools are available for use
Enhanced Context
  • • Document attachments (PDFs, DOCX, etc.)
  • • Knowledge base retrieval (RAG)
  • • Structured system prompts
  • • Agent-mode with tool execution

Context Strategies

Using Structured System Prompts

Structured prompts provide more control over how personas behave in conversations.

JavaScript
// Create persona with structured prompt
const persona = await createPersona({
  name: 'Technical Support',
  systemPrompt: 'You are a helpful technical support agent.',
  systemPromptStructured: {
    role: 'Senior Technical Support Specialist',
    task: 'Help users troubleshoot technical issues with our API',
    context: 'You have access to documentation and can look up error codes',
    reasoning: 'Always ask clarifying questions before providing solutions',
    output: 'Provide step-by-step solutions with code examples when helpful',
    stopping: 'Confirm the issue is resolved before ending the conversation'
  },
  // ... other configuration
});
Structured Prompt Components
  • Role: Who the persona is and their expertise
  • Task: Primary objective and responsibilities
  • Context: Relevant information and capabilities
  • Reasoning: How to approach problems
  • Output: Expected response format and style
  • Stopping: When to conclude interactions

Multi-turn Conversations

Design and manage complex conversations that span multiple exchanges while maintaining coherence.

Multi-turn Flow Example

Here's a typical multi-turn conversation pattern for a support interaction:

USER

"I'm having trouble with my API integration. Getting 401 errors."

ASSISTANT

"I can help with that! A 401 error typically indicates an authentication issue. Can you tell me: 1. Are you using API key or OAuth authentication? 2. Where are you passing the credentials (header, query param)?"

USER

"Using API key in the X-API-Key header"

ASSISTANT

"Good, that's the correct header. Let's verify your setup: 1. Make sure you're also including the X-Organization-ID header 2. Verify your API key hasn't expired..."

Key Patterns
  • Clarifying questions: Gather information before providing solutions
  • Step-by-step guidance: Break complex tasks into manageable steps
  • Confirmation: Verify understanding before moving forward
  • Context retention: Reference earlier information in later turns

Implementation Example

JavaScript
// Multi-turn conversation handler
async function handleConversation(sessionId, userMessage) {
  // Send message and get response
  const response = await sendMessage({
    chatSessionId: sessionId,
    content: userMessage,
    role: 'USER'
  });
  
  const { userMessage: savedUser, aiMessage } = response;
  
  // The AI automatically has access to:
  // - Recent conversation history (context)
  // - Persona system prompt and configuration
  // - Enabled tools (if useAgent is true)
  // - Knowledge base content (if configured)
    
    return {
    userMessage: savedUser,
    aiResponse: aiMessage.content,
    // Check if the AI used any tools
    toolsUsed: aiMessage.metadata?.toolCalls || []
  };
}

// Usage in a conversation loop
async function runConversation(personaId) {
  const session = await createSession({ personaId });
  
  // First turn
  const turn1 = await handleConversation(
    session.id, 
    "I need help with API authentication"
  );
  console.log('AI:', turn1.aiResponse);
  
  // Second turn (AI has context from turn 1)
  const turn2 = await handleConversation(
    session.id,
    "I'm using the X-API-Key header"
  );
  console.log('AI:', turn2.aiResponse);
  
  // Continue conversation...
}

Attachments & Documents

Send documents with messages to provide additional context for AI responses.

Sending Attachments

JavaScript
// Read file and convert to base64
const fs = require('fs');
const fileBuffer = fs.readFileSync('document.pdf');
const base64Content = fileBuffer.toString('base64');

// Send message with attachment
const response = await fetch('/api/trpc/chat.sendMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Organization-ID': orgId,
  },
  body: JSON.stringify({
    json: {
      chatSessionId: sessionId,
      content: 'Please summarize the key points from this document',
      role: 'USER',
      attachments: [{
        filename: 'document.pdf',
        mimeType: 'application/pdf',
        content: base64Content,
        size: fileBuffer.length
      }]
    }
  })
});

Supported File Types

PDF
application/pdf
DOCX
Word documents
DOC
Legacy Word
TXT
Plain text
MD
Markdown
Note
Attachments are processed using the document processor service. Text is extracted and included in the message context for the AI to reference. Large documents are automatically chunked for efficient processing.

Best Practices

Follow these best practices for effective conversation management.

Do

  • Use descriptive session titles for easy identification
  • Create separate sessions for distinct conversation topics
  • Configure appropriate temperature based on use case
  • Enable only the tools your persona actually needs
  • Use structured prompts for consistent behavior
  • Clean up unused sessions periodically
  • Test personas thoroughly before production use

Avoid

  • Creating new sessions for every single message
  • Using overly generic system prompts
  • Enabling all tools without purpose
  • Setting temperature too high for factual queries
  • Ignoring error responses from the API
  • Storing sensitive data in chat messages
  • Skipping input validation on user messages

Temperature Guidelines

0.0 - 0.3

Low (Deterministic)

Best for factual Q&A, data extraction, code generation

0.4 - 0.7

Medium (Balanced)

General conversations, customer support, explanations

0.8 - 1.0

High (Creative)

Creative writing, brainstorming, diverse responses

Troubleshooting

Common issues and their solutions when managing conversations.

Context Loss in Long Conversations

Symptom: Persona forgets earlier conversation details.

Cause: Only the last 10 messages are included by default for context.

Solutions:
  • Summarize important information in new messages
  • Use knowledge base for persistent information
  • Create new sessions with context summary when appropriate
Slow Response Times

Symptom: AI responses take a long time to generate.

Causes: Large max tokens setting, complex tools enabled, large attachments.

Solutions:
  • Reduce max tokens if full responses aren't needed
  • Only enable necessary tools
  • Process large documents before chat (use knowledge base)
Inconsistent Persona Behavior

Symptom: Persona responds differently to similar queries.

Causes: High temperature setting, vague system prompts.

Solutions:
  • Lower temperature for more consistent responses
  • Use structured prompts with clear guidelines
  • Add explicit examples in the system prompt
Session Not Found Errors

Symptom: Getting 404 errors when sending messages.

Causes: Session was deleted, wrong session ID, or wrong organization.

Solutions:
  • Verify the session ID is correct
  • Ensure X-Organization-ID header matches session's org
  • Create a new session if the old one was deleted