Logging Conversations

Log conversations to track performance and generate insights.

Why Log Conversations?

Logging conversations enables:

• Performance tracking - See how your prompts perform in production
• Insights generation - AI analyzes patterns and issues
• Optimization fuel - Real data guides improvements

Structured Format

For best results, use the structured message format instead of raw text transcripts.

Via SDK (Recommended)

The SDK makes logging easy:

import { Converra } from 'converra';
import OpenAI from 'openai';

const converra = new Converra({ apiKey: process.env.CONVERRA_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// 1. Get your prompt
const prompt = await converra.prompts.get('prompt_123');

// 2. Run your AI conversation
const messages = [
  { role: 'system', content: prompt.content },
  { role: 'user', content: userMessage }
];

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages
});

const assistantMessage = response.choices[0].message.content;

// 3. Log the conversation
await converra.conversations.create({
  promptId: 'prompt_123',
  content: `User: ${userMessage}\nAssistant: ${assistantMessage}`,
  status: 'completed',
  llmModel: 'gpt-4o'
});

Multi-Turn Conversations

For longer conversations, accumulate messages:

class ConversationLogger {
  private messages: string[] = [];

  addUserMessage(message: string) {
    this.messages.push(`User: ${message}`);
  }

  addAssistantMessage(message: string) {
    this.messages.push(`Assistant: ${message}`);
  }

  async log(promptId: string) {
    await converra.conversations.create({
      promptId,
      content: this.messages.join('\n'),
      status: 'completed'
    });
  }
}

// Usage
const logger = new ConversationLogger();

logger.addUserMessage("Hi, I need help with my order");
logger.addAssistantMessage("I'd be happy to help! What's your order number?");
logger.addUserMessage("#12345");
logger.addAssistantMessage("Found it! Your order ships tomorrow.");
logger.addUserMessage("Thanks!");
logger.addAssistantMessage("You're welcome! Anything else?");

await logger.log('prompt_123');

Via API

curl -X POST https://converra.ai/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "prompt_123",
    "content": "User: Hello\nAssistant: Hi there! How can I help?",
    "status": "completed",
    "llmModel": "gpt-4o"
  }'

Via MCP

Log this conversation for my support prompt:

User: How do I cancel my subscription?
Assistant: I can help you cancel. Go to Settings > Subscription > Cancel.
User: Thanks!
Assistant: You're welcome! Your subscription will end on the billing date.

Conversation Format

Converra accepts two formats for conversation content.

Structured Format (Recommended)

Use a JSON messages array for best parsing and analysis:

await converra.conversations.create({
  promptId: 'prompt_123',
  content: JSON.stringify({
    messages: [
      { role: 'user', content: 'I need help with my order' },
      { role: 'assistant', content: 'I\'d be happy to help! What\'s your order number?' },
      { role: 'user', content: '#12345' },
      { role: 'assistant', content: 'Found it! Your order ships tomorrow.' }
    ]
  }),
  status: 'completed',
  llmModel: 'gpt-4o'
});

Benefits:

• Precise message boundaries
• Role attribution is unambiguous
• Metadata can be included per message
• Direct compatibility with OpenAI/Anthropic formats

Extended format with metadata:

{
  "messages": [
    {
      "role": "user",
      "content": "I need help with my order",
      "timestamp": "2025-01-20T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help! What's your order number?",
      "timestamp": "2025-01-20T14:30:02Z",
      "model": "gpt-4o",
      "tokens": 15
    }
  ],
  "metadata": {
    "userId": "user_123",
    "sessionId": "sess_456",
    "channel": "web",
    "language": "en"
  }
}

Text Format

For simpler integrations, use alternating labeled messages:

User: First user message
Assistant: First assistant response
User: Second user message
Assistant: Second assistant response

Accepted labels:

• User / Assistant
• Human / AI
• Customer / Agent

WARNING

Text format may have parsing issues with multi-line messages or messages containing colons. Use structured format for production.

Status Options

Status	Use When
completed	Conversation ended naturally
abandoned	User left without resolution
in_progress	Conversation still ongoing

Optional Metadata

Include additional context:

await converra.conversations.create({
  promptId: 'prompt_123',
  content: conversationText,
  status: 'completed',
  llmModel: 'gpt-4o',
  // Optional
  companyName: 'Acme Corp',       // Customer company
  // Add custom fields as needed
});

Best Practices

Log All Conversations

Even "bad" conversations provide valuable data:

• Abandoned sessions reveal pain points
• Errors show edge cases to handle
• Short conversations might indicate unclear prompts

Log Promptly

Log conversations soon after they complete:

• Data is fresh and accurate
• Insights are timely
• Performance tracking is current

Use Consistent Formatting

Keep the same format across all logged conversations:

• Same labels (User/Assistant or Human/AI)
• Same line breaks
• Same structure

Handle Errors Gracefully

Don't let logging failures break your app:

try {
  await converra.conversations.create({ ... });
} catch (error) {
  console.error('Failed to log conversation:', error);
  // Continue - logging failure shouldn't break user experience
}

Viewing Logged Conversations

Dashboard

View all conversations at converra.ai/conversations

Via SDK

const { data: conversations } = await converra.conversations.list({
  promptId: 'prompt_123',
  limit: 20
});

Next Steps

• Analyzing Insights - Understand patterns
• Running Optimizations - Improve based on data