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.
Conversation Lifecycle
Understanding the conversation lifecycle helps you design better user experiences and implement appropriate management strategies at each stage.
Conversation Stages
Session Creation
Create a chat session with a specific persona.
// 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'
}
})
});Message Exchange
Send messages and receive AI-generated responses.
// 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();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
Session Closure
Archive or delete sessions when complete.
// 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.
// 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.
// 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:
"I'm having trouble with my API integration. Getting 401 errors."
"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)?"
"Using API key in the X-API-Key header"
"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
// 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
// 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
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
Low (Deterministic)
Best for factual Q&A, data extraction, code generation
Medium (Balanced)
General conversations, customer support, explanations
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.
- 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.
- 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.
- 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.
- 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