Conversation Logs

Import your production conversations into Voxli for analysis and evaluation. External conversation logs let you bring real-world chat sessions from your AI agent into the platform.

Use Cases

• Analyze production conversations to identify patterns and issues
• Evaluate agent performance on real customer interactions
• Build test cases from actual conversations that revealed problems
• Track conversation quality over time with metadata filtering

Message Format

Each conversation is a list of messages with the following structure:

• role: Either "chatbot" (your AI agent) or "user" (the user/customer)
• type: "message" for text, "tool" for tool calls, "internal-event" for events only visible to scoring, or "public-event" for events visible in conversation history
• content: The message text (for message type)
• name: Tool name (for tool type)
• metadata: Optional data for tool calls

Example

Here’s how to create, list, update, and delete conversation logs:

"""
Example: Import and manage external conversation logs in Voxli.

Use this to analyze production conversations from your chatbot or AI agent.
"""

import os
import requests
from datetime import datetime, timezone

api_key = os.getenv("VOXLI_API_KEY")
base_url = os.getenv("VOXLI_API_URL", "https://api.voxli.io")

headers = {"Authorization": f"Bearer {api_key}"}

# Create a conversation log
conversation_log = requests.post(f"{base_url}/external-conversation-logs/", headers=headers, json={
    "externalId": "chat-session-12345",
    "timestamp": datetime.now(timezone.utc).isoformat(),
    "conversation": [
        {"role": "user", "type": "message", "content": "Hi, I need help with my order"},
        {"role": "chatbot", "type": "message", "content": "Hello! I'd be happy to help. What's your order number?"},
        {"role": "user", "type": "message", "content": "It's #98765"},
        {"role": "chatbot", "type": "tool", "name": "lookup_order", "metadata": {"order_id": "98765"}},
        {"role": "chatbot", "type": "message", "content": "I found your order. It shipped yesterday and should arrive by Friday."},
        {"role": "user", "type": "message", "content": "Thank you!"},
    ],
    "metadata": {
        "source": "production",
        "channel": "web-widget",
        "customer_id": "cust_abc123"
    },
    "description": "Order tracking inquiry",
    "agents": ["your_agent_id"]  # Optional: link agents to this log
}).json()

log_id = conversation_log["id"]
print(f"Created conversation log: {log_id}")

# List all conversation logs (paginated)
logs = requests.get(f"{base_url}/external-conversation-logs/", headers=headers, params={
    "page": 1,
    "limit": 10,
    "sortBy": "timestamp",
    "sortOrder": "desc"
}).json()

print(f"Found {logs['total']} conversation logs")

# Get a specific log
log = requests.get(f"{base_url}/external-conversation-logs/{log_id}", headers=headers).json()
print(f"Log has {len(log['conversation'])} messages")

# Update a log (e.g., add description and link agents)
requests.patch(f"{base_url}/external-conversation-logs/{log_id}", headers=headers, json={
    "description": "Order tracking - resolved",
    "agents": ["agent_id_1", "agent_id_2"]
})

# Delete a log
requests.delete(f"{base_url}/external-conversation-logs/{log_id}", headers=headers)
print("Log deleted")

Metadata

The metadata field accepts any JSON object. Use it to store context about the conversation:

"metadata": {
    "source": "production",
    "channel": "web-widget",
    "customer_id": "cust_abc123",
    "agent_version": "v2.1.0",
    "session_duration_seconds": 245,
    "responseTime": 1250
}

External ID

The externalId field is required and should be a unique identifier from your system (e.g., session ID, chat ID). This helps you correlate logs in Voxli with your own data.

Timestamp

The timestamp field should be provided in UTC timezone (ISO 8601 format). If not provided, it defaults to the current UTC time. The timestamp will be automatically converted to the user’s local timezone when displayed in the Voxli interface.

Example:

from datetime import datetime, timezone

"timestamp": datetime.now(timezone.utc).isoformat()

Linking Agents

You can link agents to a conversation log using the agents field. Pass a list of agent IDs when creating or updating a log:

# During creation
requests.post(f"{base_url}/external-conversation-logs/", headers=headers, json={
    "externalId": "chat-session-12345",
    "conversation": [...],
    "agents": ["agent_id_1", "agent_id_2"]
})

# Or update an existing log
requests.patch(f"{base_url}/external-conversation-logs/{log_id}", headers=headers, json={
    "agents": ["agent_id_1"]
})

When agents are linked to a conversation log, only those agents can be used for re-runs of the conversation.