Session Management

Overview

Chat2API supports two conversation modes for different use cases. Session management maintains conversation context across multiple API calls.

Session Modes

Single-Turn Mode

Each request is independent with no context retention.

Characteristics:

Best For:

• Simple Q&A
• Translation tasks
• Text generation
• One-off queries

Delete After Timeout:

In single-turn mode, enable deleteAfterTimeout to automatically delete the provider-side conversation after chat ends. This helps:

• Save provider storage
• Maintain privacy
• Clean up unused conversations

Multi-Turn Mode

Conversation context is maintained within the same session.

Characteristics:

Best For:

• Conversational AI applications
• Multi-step tasks
• Context-dependent queries
• Customer support bots

Configuration

Configure in Advanced Settings → Proxy → Session Management:

Using Sessions

Creating a Session

Sessions are automatically created when you include a session_id in your request:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "DeepSeek-V3.2",
    "messages": [
      {"role": "user", "content": "My name is Alice"}
    ],
    "session_id": "user-123-session"
  }'

Continuing a Session

Use the same session_id to continue the conversation:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "DeepSeek-V3.2",
    "messages": [
      {"role": "user", "content": "What is my name?"}
    ],
    "session_id": "user-123-session"
  }'

The model remembers the context and responds: "Your name is Alice."

Session ID Format

Session Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │ ──▶ │   Active    │ ──▶ │   Expired   │ ──▶ │   Cleaned   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

States

Session Limits

Message Limit

When a session reaches maxMessagesPerSession:

1. Oldest messages are removed first
2. Recent context is preserved
3. Session continues to function normally

Session Count Limit

When an account reaches maxSessionsPerAccount:

1. Oldest inactive sessions are removed
2. New sessions can be created
3. Active sessions are not affected

Session Management UI

The Session Management page provides:

Session Information Display

Each session shows:

• Session ID
• Provider and Account
• Message count
• Status (active/expired)
• Last active time

Automatic Cleanup

The system automatically cleans up expired sessions:

Best Practices

Session ID Management

1. Use UUIDs: Generate unique IDs for each conversation
2. User Association: Tie session IDs to user identifiers
3. Consistent Format: Use a consistent naming convention

Configuration Tuning

Resource Management

1. Monitor Usage: Check session list periodically
2. Set Appropriate Limits: Balance functionality and resources
3. Clean Up Proactively: Use the Clear All function when needed

Troubleshooting

Session Not Working

Checklist:

• Session mode is Multi-turn
• session_id is included in request
• Session has not expired
• Using the same session_id across requests

Context Lost

Possible Causes:

Too Many Sessions

Solutions:

1. Reduce maxSessionsPerAccount
2. Decrease sessionTimeout for faster cleanup
3. Use the Clear All function in UI
4. Implement session cleanup in your application

Provider Session Not Deleted (Single-Turn)

If deleteAfterTimeout is enabled but provider sessions persist:

• Check if the provider supports session deletion
• Verify the account has proper permissions
• Check logs for deletion errors