Get Chat Session by ID

Used to retrieve detailed information about a specific chat session, including all messages and conversation history. This endpoint provides complete conversation data with pagination support.

API Endpoint

Property	Value
Request Method	`POST`
Request URL	`https://api.seliseblocks.com/conversation/sessions/{session_id}`

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/conversation/sessions/session_abc123' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "widget_id": "widget_456",
    "session_id": "session_abc123",
    "agent_id": "agent_789",
    "limit": 50,
    "offset": 0,
    "project_key": "YOUR_PROJECT_KEY"
  }'

Path Parameters

Field	Type	Required	Description
session_id	string	Yes	The unique identifier of the chat session.

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use `application/json`
Content-Type	application/json	Yes	Data type, must be `application/json`.

Request Body

Request Body Schema

{
  "widget_id": "string",
  "session_id": "string",
  "agent_id": "string",
  "limit": 100,
  "offset": 0,
  "project_key": "string"
}

Request Body Parameters

Field	Type	Required	Description
widget_id	string	Yes	The unique identifier of the chat widget.
session_id	string	Yes	The session ID (should match path parameter).
agent_id	string	Yes	The unique identifier of the AI agent.
limit	integer	No	Maximum number of messages to return per request (default: 100, max: 100).
offset	integer	No	Number of messages to skip for pagination (default: 0).
project_key	string	Yes	The project key for your project.

tip

When to use this endpoint:

Conversation replay: Display full conversation history to users
Customer support: Review past interactions for context
Quality assurance: Audit specific conversations
Analytics: Analyze conversation flow and patterns
Debugging: Troubleshoot issues with specific sessions
Export: Extract conversation data for reporting or archival

Message pagination:

Messages are typically ordered chronologically (oldest to newest)
Use limit and offset to load conversations incrementally
Load initial messages with offset=0, then paginate for older messages
Implement "load more" or infinite scroll UI patterns
For long conversations, fetch messages in batches

Use cases:

Chat history UI: Display conversation in a scrollable interface
Transcript export: Generate PDF or text transcripts
Sentiment analysis: Analyze conversation tone and satisfaction
Training data: Extract conversations for model improvement
Compliance: Maintain records for legal or regulatory purposes
Context restoration: Restore conversation state after reconnection

Response

Success Response (200 OK)

Returns detailed session information with paginated message history.

{
  "sessions": [
    {
      "_id": "64a1b2c3d4e5f6789012345",
      "SessionId": "session_abc123",
      "WidgetId": "widget_456",
      "AgentId": "agent_789",
      "CreatedAt": "2026-01-12T08:30:00Z",
      "Query": "How do I reset my password?",
      "QueryId": "query_001",
      "Response": "I'll help you reset your password. You can do this by clicking the 'Forgot Password' link on the login page.",
      "NextStepQuestions": [
        "What should I do if I don't receive the reset email?",
        "How long does the reset link stay valid?",
        "Can I change my password from my account settings?"
      ],
      "ResponseId": "response_001",
      "Filters": {
        "category": "account_support",
        "priority": "medium"
      },
      "Metadata": {
        "user_agent": "Mozilla/5.0...",
        "ip_address": "192.168.1.1",
        "referrer": "https://example.com/login"
      },
      "QueryTimestamp": "2026-01-12T08:30:15Z",
      "ResponseTimestamp": "2026-01-12T08:30:18Z",
      "ConversationType": "chat",
      "UserId": "user_123",
      "UserEmail": "john@example.com",
      "UserRole": ["customer", "premium"],
      "Summary": "User requested password reset assistance",
      "Playground": false,
      "IsPrivate": false,
      "WorkflowName": "account_support_workflow",
      "TokenUsage": "input: 120, output: 85, total: 205",
      "WorkflowTrace": {
        "steps": ["intent_classification", "knowledge_retrieval", "response_generation"],
        "execution_time_ms": 450
      },
      "Error": null
    },
    {
      "_id": "64a1b2c3d4e5f6789012346",
      "SessionId": "session_abc123",
      "WidgetId": "widget_456",
      "AgentId": "agent_789",
      "CreatedAt": "2026-01-12T08:31:00Z",
      "Query": "I didn't receive the reset email",
      "QueryId": "query_002",
      "Response": "Let me check a few things. First, please verify that you entered the correct email address. Also, check your spam or junk folder.",
      "NextStepQuestions": [
        "What email address did you use?",
        "Have you checked your spam folder?",
        "When did you request the reset?"
      ],
      "ResponseId": "response_002",
      "Filters": {
        "category": "account_support",
        "priority": "high"
      },
      "Metadata": {
        "follow_up": true,
        "related_query_id": "query_001"
      },
      "QueryTimestamp": "2026-01-12T08:31:05Z",
      "ResponseTimestamp": "2026-01-12T08:31:08Z",
      "ConversationType": "chat",
      "UserId": "user_123",
      "UserEmail": "john@example.com",
      "UserRole": ["customer", "premium"],
      "Summary": "User reports not receiving password reset email",
      "Playground": false,
      "IsPrivate": false,
      "WorkflowName": "account_support_workflow",
      "TokenUsage": "input: 95, output: 120, total: 215",
      "WorkflowTrace": {
        "steps": ["context_retrieval", "troubleshooting", "response_generation"],
        "execution_time_ms": 380
      },
      "Error": null
    }
  ],
  "total_count": 15
}

Response Fields

Field	Type	Description
sessions	array	Array of message objects representing the conversation history.
total_count	integer	Total number of messages in the session (for pagination).

note

Message Object Structure

Each message object in the sessions array contains:

Identifiers:

_id: MongoDB object ID for the message
SessionId: Session identifier
WidgetId: Widget used for the conversation
AgentId: AI agent handling the conversation
QueryId: Unique identifier for the user query
ResponseId: Unique identifier for the agent response

Conversation Content:

Query: User's message/question
Response: Agent's reply
NextStepQuestions: Suggested follow-up questions for the user
Summary: Brief summary of the message exchange

Timestamps:

CreatedAt: Message creation timestamp (ISO 8601)
QueryTimestamp: When user sent the query
ResponseTimestamp: When agent responded

Categorization:

ConversationType: Type of conversation (chat, voice, email, etc.)
Filters: Message categorization and routing filters
Metadata: Additional contextual information

User Information:

UserId: User identifier
UserEmail: User's email address
UserRole: Array of user roles or permissions

Workflow and Performance:

WorkflowName: Name of the workflow that processed the message
TokenUsage: AI model token consumption statistics
WorkflowTrace: Detailed execution trace for debugging
Error: Error message if processing failed (null if successful)

Privacy and Settings:

Playground: Whether this is a test/playground conversation
IsPrivate: Privacy flag for sensitive conversations

Error Response (422 Unprocessable Entity)

Returns validation error details when request parameters are invalid or session not found.

{
  "detail": [
    {
      "loc": [
        "path",
        "session_id"
      ],
      "msg": "Session not found or access denied",
      "type": "value_error.notfound"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., path, body field).
msg	string	Human-readable error message.
type	string	Error type identifier.

Common Error Scenarios

Error Type	Description	Resolution
Session Not Found	The specified session_id doesn't exist	Verify session_id is correct
Access Denied	Insufficient permissions to view session	Check API credentials and permissions
Mismatched IDs	Path session_id doesn't match body session_id	Ensure both session_id values are identical
Invalid Agent	Agent_id doesn't match session's agent	Use correct agent_id for the session
Invalid Widget	Widget_id doesn't match session's widget	Use correct widget_id for the session
Invalid Project Key	Project key is incorrect	Verify project_key credentials
Invalid Pagination	Limit or offset values out of range	Ensure limit ≤ 100 and offset ≥ 0

Error Codes

Status Code	Description	Response Type
200	OK - Session retrieved successfully	Success
400	Bad Request - Invalid request format	Bad Request
401	Unauthorized - Authentication required	Unauthorized
403	Forbidden - Access denied to session	Forbidden
404	Not Found - Session doesn't exist	Not Found
422	Validation Error - Invalid parameters	Unprocessable Entity
500	Internal Server Error - Failed to fetch session	Internal Server Error

warning

Important Considerations

Data privacy: Session data may contain sensitive user information; handle securely
GDPR compliance: Respect user data deletion and export requests
Performance: Large conversations may require multiple paginated requests
Real-time updates: Messages may be added during retrieval; implement refresh logic
Token usage: Review TokenUsage field to monitor AI costs per message
Error handling: Check Error field to identify failed message processing
Caching: Cache session data appropriately to reduce API load
Message order: Messages are typically chronological; verify order in your UI
Metadata: Extract custom metadata for analytics and reporting
Workflow traces: Use WorkflowTrace for debugging complex agent behaviors
Next step questions: Implement suggested questions for better UX
Rate limiting: Avoid excessive session detail requests

API Endpoint​

Request​

Request Example​

Path Parameters​

Request Headers​

Request Body​

Request Body Schema​

Request Body Parameters​

Response​

Success Response (200 OK)​

Response Fields​

Error Response (422 Unprocessable Entity)​

Error Response Fields​

Common Error Scenarios​

Error Codes​