Conversations

Manage and organize chat message threads with persistent history.

Overview

Conversations provide:

• Grouped message history by thread
• Per-conversation context isolation
• Message count and timestamp tracking
• Concurrent request locking
• Up to 50 conversations per agent

Conversation Structure

Conversation
├── ID (unique identifier)
├── Title (display name)
├── Messages (chat history)
├── Message Count
├── Last Message At
└── Created At

Creating Conversations

Automatic Creation

Conversations are created automatically when:

• A message is sent without a conversationId
• The chat interface "New Conversation" button is clicked

Via API

curl -X POST https://your-domain.com/api/agents/{id}/chat/conversations \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Technical Support"
  }'

Response:

{
  "id": "conv-abc123",
  "title": "Technical Support",
  "messageCount": 0,
  "createdAt": "2024-12-15T10:00:00Z"
}

Listing Conversations

Get All Conversations

curl "https://your-domain.com/api/agents/{id}/chat/conversations"

Response:

{
  "conversations": [
    {
      "id": "conv-123",
      "title": "Product Questions",
      "messageCount": 15,
      "lastMessageAt": "2024-12-15T10:30:00Z",
      "createdAt": "2024-12-15T10:00:00Z"
    },
    {
      "id": "conv-456",
      "title": "Technical Support",
      "messageCount": 8,
      "lastMessageAt": "2024-12-14T15:20:00Z",
      "createdAt": "2024-12-14T15:00:00Z"
    }
  ]
}

Conversations are sorted by lastMessageAt (most recent first), limited to 50.

Message Threading

Send Message to Conversation

Include conversationId to continue an existing conversation:

curl -X POST https://your-domain.com/api/agents/{id}/chat \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What about my order?",
    "conversationId": "conv-123"
  }'

Start New Conversation

Omit conversationId to start fresh:

curl -X POST https://your-domain.com/api/agents/{id}/chat \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello!"
  }'

The response includes the new conversationId:

{
  "userMessage": {
    "id": "msg_abc123",
    "conversationId": "conv-new-789",
    ...
  },
  "assistantMessage": {
    "id": "msg_def456",
    "conversationId": "conv-new-789",
    ...
  }
}

Context Isolation

Each conversation maintains isolated context:

• Messages are grouped by conversation
• AI only sees messages from the current conversation
• System prompt is shared across conversations
• Token-aware trimming happens per conversation

Conversation Locking

The system prevents concurrent processing:

1. When a message is sent, the conversation is locked
2. Additional requests to the same conversation return 409 Conflict
3. Lock is released when streaming completes or request finishes
4. Prevents race conditions and duplicate responses

{
  "error": "Conversation is currently being processed",
  "code": "CONVERSATION_LOCKED"
}

Deleting Conversations

Delete Single Conversation

curl -X DELETE "https://your-domain.com/api/agents/{id}/chat/conversations/{conversationId}"

This deletes the conversation and all its messages.

Clear All History

curl -X DELETE "https://your-domain.com/api/agents/{id}/chat"

This deletes all conversations and messages for the agent.

Message Management

Get Messages for Conversation

curl "https://your-domain.com/api/agents/{id}/chat?conversationId=conv-123&limit=50"

Delete Single Message

curl -X DELETE "https://your-domain.com/api/agents/{id}/chat/messages/{messageId}"

Regenerate Response

Regenerate the AI's response for a specific message:

curl -X POST "https://your-domain.com/api/agents/{id}/chat/messages/{messageId}/regenerate" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true
  }'

Frontend Integration

useChat Hook

The useChat hook manages conversations in React:

const {
  conversations,         // List of all conversations
  currentConversation,   // Active conversation ID
  messages,              // Messages in current conversation
  createConversation,    // Create new conversation
  deleteConversation,    // Delete conversation
  sendMessage,           // Send message
  clearHistory           // Clear all messages
} = useChat(agentId)

Conversation Sidebar

The chat interface displays conversations in a sidebar:

• Click to switch conversations
• "New Conversation" button to start fresh
• Delete icon to remove conversations
• Message count and last activity shown

Streaming State Recovery

When streaming is interrupted:

1. State is saved to localStorage with conversation ID
2. On page reload, streaming state is recovered
3. Frontend polls server for completion
4. Recovery expires after 5 minutes

Best Practices

1. Use Conversations for Context

Group related messages:

• One conversation per topic
• One conversation per customer session
• One conversation per task

2. Clean Up Old Conversations

Periodically delete unused conversations:

• Reduces storage
• Improves list load time
• Maintains organization

3. Handle Concurrent Requests

When building integrations:

• Check for 409 status code
• Retry after a short delay
• Or queue requests per conversation

4. Title Conversations

Give conversations meaningful titles:

• Easier to find later
• Better organization
• Helps users navigate

API Reference

Method	Endpoint	Description
GET	/api/agents/{id}/chat/conversations	List conversations
POST	/api/agents/{id}/chat/conversations	Create conversation
DELETE	/api/agents/{id}/chat/conversations/{id}	Delete conversation
GET	/api/agents/{id}/chat	Get messages
POST	/api/agents/{id}/chat	Send message
DELETE	/api/agents/{id}/chat	Clear all history
DELETE	/api/agents/{id}/chat/messages/{id}	Delete message
POST	/api/agents/{id}/chat/messages/{id}/regenerate	Regenerate response

See Chat API for complete endpoint documentation.