Chat History & Conversation Management

⚠️ Plan Requirement

Chat history API access requires Starter plan or higher.

View plan features →

Manage conversation history, retrieve messages, and build conversation management features using the dialektai Chat History API.

When to Use This API

Use the Chat History API when you need to:

Display conversation history in custom UIs
List all conversations for a user across your application
Retrieve messages from specific conversations with pagination
Manually append messages to conversations programmatically
Delete conversations for data cleanup or privacy compliance
Build conversation management features (search, archive, export)

Prerequisites

Before you begin, you'll need:

dialektai organization account with Starter plan or higher
Organization API key (sk_*) - see API Integration Guide
X-Scope-Id header - User/customer identifier for conversation tracking

ℹ️ Required Header: X-Scope-Id

All chat history endpoints require the X-Scope-Id header to identify the end-user scope. This ensures conversations are properly isolated per user.

Example: X-Scope-Id: user-123 or X-Scope-Id: customer-456

Authentication

Chat History API uses the same authentication as standard API integration:

Headers Required:

X-API-Key: sk_your_organization_key_here
X-Scope-Id: user-123
Content-Type: application/json

For details on creating organization API keys, see the API Integration Guide - Authentication.

Conversation Management

List Conversations

Get a paginated list of all conversations for a specific user.

Endpoint: GET /api/v1/chat/conversations

Query Parameters:

Parameter	Type	Required	Default	Description
`limit`	integer	No	20	Max conversations to return (max: 100)
`cursor`	string	No	null	Pagination cursor from previous response

Example Request:

curl -X GET "https://api.dialektai.com/api/v1/chat/conversations?limit=20" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123"

Response:

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "organizationId": 42,
        "scopeId": "user-123",
        "title": "Sales Analysis",
        "lastMessageAt": "2025-01-15T14:30:00Z",
        "messageCount": 12,
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ],
    "cursor": "eyJpZCI6IjEyMyIsInRpbWVzdGFtcCI6MTY0NzM1MjAwMH0=",
    "hasMore": true
  }
}

Get Conversation Messages

Retrieve messages from a specific conversation or all messages for a user.

Endpoint: GET /api/v1/chat/history

Query Parameters:

Parameter	Type	Required	Default	Description
`conversation_id`	string (UUID)	No	null	Filter by specific conversation
`limit`	integer	No	50	Max messages to return (max: 200)
`cursor`	string	No	null	Pagination cursor from previous response

Example Request (Specific Conversation):

curl -X GET "https://api.dialektai.com/api/v1/chat/history?conversation_id=550e8400-e29b-41d4-a716-446655440000&limit=50" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123"

Example Request (All User Messages):

curl -X GET "https://api.dialektai.com/api/v1/chat/history?limit=50" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123"

Response:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg-001",
        "content": "Show me top customers by revenue",
        "sender": "USER",
        "timestamp": "2025-01-15T10:05:00Z",
        "type": "text",
        "metadata": {}
      },
      {
        "id": "msg-002",
        "content": "Here are the top 10 customers by revenue...",
        "sender": "ASSISTANT",
        "timestamp": "2025-01-15T10:05:03Z",
        "type": "text",
        "metadata": {
          "query_type": "data_retrieval",
          "execution_time_ms": 1234
        }
      }
    ],
    "cursor": "eyJpZCI6Im1zZy0wMDIiLCJ0aW1lc3RhbXAiOjE2NDczNTIwMDB9",
    "hasMore": true
  }
}

Pagination

The Chat History API uses cursor-based pagination for efficient data retrieval.

How it works:

Make initial request (no cursor)
Check hasMore in response
If hasMore: true, use cursor value in next request
Repeat until hasMore: false

Example Pagination Loop (Python):

import requests

API_KEY = "sk_your_key_here"
SCOPE_ID = "user-123"

def get_all_conversations():
    """Fetch all conversations with pagination."""
    conversations = []
    cursor = None

    while True:
        url = "https://api.dialektai.com/api/v1/chat/conversations"
        params = {"limit": 20}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            url,
            params=params,
            headers={
                "X-API-Key": API_KEY,
                "X-Scope-Id": SCOPE_ID
            }
        )

        data = response.json()["data"]
        conversations.extend(data["conversations"])

        if not data["hasMore"]:
            break

        cursor = data["cursor"]

    return conversations

# Usage
all_conversations = get_all_conversations()
print(f"Total conversations: {len(all_conversations)}")

Session-Specific Operations

Send Message to Session

Send a message to a specific conversation session (alternative to simple POST /api/v1/chat/message).

Endpoint: POST /api/v1/chat/{session_id}/message

Rate Limits:

Burst: 30 requests/minute per organization
Sustained: 200 requests/hour per organization

Example Request:

curl -X POST "https://api.dialektai.com/api/v1/chat/550e8400-e29b-41d4-a716-446655440000/message" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were the top products last quarter?",
    "database_id": "db-uuid-here"
  }'

Response:

{
  "success": true,
  "data": {
    "message": "Based on your data, here are the top products...",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "sources": [...],
    "query_type": "data_retrieval",
    "execution_time_ms": 1456
  }
}

Get Session History

Retrieve conversation history for a specific session from PostgreSQL storage.

Endpoint: GET /api/v1/chat/{session_id}/history

Example Request:

curl -X GET "https://api.dialektai.com/api/v1/chat/550e8400-e29b-41d4-a716-446655440000/history" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123"

Response:

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [
      {
        "role": "USER",
        "content": "Show me sales data",
        "timestamp": "2025-01-15T10:00:00Z"
      },
      {
        "role": "ASSISTANT",
        "content": "Here is your sales data...",
        "timestamp": "2025-01-15T10:00:03Z"
      }
    ],
    "organization_id": 42,
    "user_id": 123
  }
}

Delete Session

Delete a conversation session and all its messages from PostgreSQL storage.

Endpoint: DELETE /api/v1/chat/{session_id}

Example Request:

curl -X DELETE "https://api.dialektai.com/api/v1/chat/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123"

Response:

{
  "success": true,
  "data": {
    "message": "Session deleted successfully"
  }
}

Advanced Usage

Manually Append Messages

Programmatically add messages to conversations without going through the chat agent flow.

Endpoint: POST /api/v1/chat/message (history append)

Use Cases:

Import historical conversations from other systems
Add system messages or notifications to conversation threads
Create conversation templates
Programmatically manage conversation state

Request Body:

Parameter	Type	Required	Description
`conversation_id`	string (UUID)	Yes	Target conversation
`role`	string	Yes	Message role: `user`, `assistant`, `system`, `tool`
`content`	string	Yes	Message content (min 1 character)
`metadata`	object	No	Optional metadata dictionary

Example Request:

curl -X POST "https://api.dialektai.com/api/v1/chat/message" \
  -H "X-API-Key: sk_your_organization_key_here" \
  -H "X-Scope-Id: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "role": "user",
    "content": "What is the status of my order?",
    "metadata": {
      "source": "mobile_app",
      "app_version": "2.1.0"
    }
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "message_id": "987e6543-e21b-54d3-a456-426614174999",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-10-09T12:34:56.789Z"
  },
  "message": "Message appended successfully"
}

Message Roles:

user - End-user messages
assistant - AI-generated responses
system - System notifications or instructions
tool - Tool execution results

Common Use Cases

Building a Conversation History UI

List conversations with GET /api/v1/chat/conversations
Display conversation list with titles and metadata
Load messages when user selects conversation with GET /api/v1/chat/history?conversation_id=...
Paginate through messages as user scrolls
Delete conversations with DELETE /api/v1/chat/{session_id}

Conversation Search and Export

Retrieve all messages with GET /api/v1/chat/history (no conversation_id)
Filter and search messages in your application
Export to CSV/PDF for reporting or compliance
Archive old conversations to external storage

Multi-User Conversation Management

Use X-Scope-Id to isolate conversations per user
Create conversations for each user independently
Query conversations filtered by scope ID
Delete user data for GDPR compliance

Error Handling

Common Errors

Status	Error Code	Description	Solution
400	`VALIDATION_ERROR`	Missing or invalid parameters	Check request body/params
401	`UNAUTHORIZED`	Invalid API key	Verify organization API key
403	`FORBIDDEN`	Missing X-Scope-Id header	Add X-Scope-Id header
404	`NOT_FOUND`	Conversation/session not found	Verify conversation ID exists
429	`RATE_LIMIT_EXCEEDED`	Too many requests	Implement rate limiting

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid conversation_id format",
    "details": "Expected UUID format"
  }
}

Best Practices

Always include X-Scope-Id - Required for all chat history endpoints
Use cursor pagination - More efficient than offset-based pagination
Handle hasMore correctly - Check before making next page request
Set appropriate limits - Balance between requests and payload size
Implement retry logic - Handle rate limits and transient errors
Clean up old conversations - Use DELETE endpoint for data hygiene
Validate conversation IDs - Check for 404 errors and handle gracefully

Security Considerations

Never expose organization API keys in client-side code
Validate X-Scope-Id to prevent cross-user data access
Implement rate limiting in your application
Sanitize user input before appending messages
Audit conversation deletions for compliance tracking

Next Steps

API Integration Guide - Main API integration documentation
Widget Integration Guide - Pre-built widget integration
API Keys Guide - Authentication and key management
Rate Limiting Guide - Rate limits and best practices

Getting Started

Authentication

Integrations

Advanced

Resources

API Reference

Chat History & Conversation Management

When to Use This API

Prerequisites

Authentication

Conversation Management

List Conversations

Get Conversation Messages

Pagination

Session-Specific Operations

Send Message to Session

Get Session History

Delete Session

Advanced Usage

Manually Append Messages

Common Use Cases

Building a Conversation History UI

Conversation Search and Export

Multi-User Conversation Management

Error Handling

Common Errors

Error Response Format

Best Practices

Security Considerations

Next Steps