Conversations History API

Access complete conversation history with filtering and pagination

This API endpoint provides access to the complete history of business message conversations with advanced filtering and pagination capabilities. It’s designed for administrative dashboards, reporting, and analytics purposes.

API Endpoint

GET /api/business_messages/all-threads-history

Authentication: Requires staff-level permissions

Content-Type: application/json Response Format: JSON with pagination

Overview

The conversations history API allows administrators to:

• Retrieve paginated conversation threads
• Filter conversations by multiple criteria
• Access detailed thread information including user data, evaluations, and metadata
• Export and analyze conversation patterns

Request Parameters

All parameters are optional and can be combined for advanced filtering:

Date Filtering

Parameter	Type	Description
start_date	string	Filter conversations created after this date (ISO format)
end_date	string	Filter conversations created before this date (ISO format)

User Filtering

Parameter	Type	Description
email	string	Filter by user email address
user_type	string	Filter by user permission type
reviewer_email	string	Filter by reviewer email address

Conversation Content

Parameter	Type	Description
agent_name	string	Filter by AI agent name used in conversation
tag	string	Filter by conversation tag
evaluation	string	Filter by thread evaluation status

Conversation Status

Parameter	Type	Description
support_asked	boolean	Filter conversations where human support was requested
need_review	boolean	Filter conversations that need manual review
ticket_created	boolean	Filter conversations where a support ticket was created

Knowledge Base

Parameter	Type	Description
knowledge_source	string	Filter by knowledge source used
knowledge_page_id	string	Filter by specific knowledge page ID

Pagination

Parameter	Type	Description
page	integer	Page number for pagination (default: 1)

Message Data

Parameter	Type	Description
include_messages	boolean	Include full message details within each thread (default: false)

Note: Each page contains 50 conversations. Use the count field in the response to calculate total pages.

Response Format

The API returns a paginated response with the following structure:

{
  "count": 1250,
  "items": [
    {
      "id": "thread-uuid",
      "title": "Conversation title",
      "last_message_date": "2024-12-06T14:30:00Z",
      "creation_date": "2024-12-06T14:25:00Z",
      "evaluation": "good",
      "llm_judge_evaluated": true,
      "llm_judge_need_review": false,
      "llm_judge_improvement": "No improvements needed",
      "user": {
        "id": "user-uuid",
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
      },
      "reviewer": {
        "id": "reviewer-uuid",
        "email": "[e-mail]",
        "first_name": "Admin",
        "last_name": "User"
      },
      "agent_names": [
        "Customer Support AI",
        "Technical AI"
      ],
      "messages_count": 8,
      "ask_to_talk_to_human": false,
      "user_type": "premium",
      "tags": [
        {
          "id": "tag-uuid",
          "name": "billing"
        }
      ],
      "ticket_created": false
    }
  ]
}

Response Fields

Thread Information

• id: Unique thread identifier
• title: Conversation title/subject
• last_message_date: Timestamp of the last message
• creation_date: Thread creation timestamp
• messages_count: Total number of messages in the thread

Evaluation & Quality

• evaluation: Manual evaluation status (good, bad, neutral, etc.)
• llm_judge_evaluated: Whether AI judge has evaluated the conversation
• llm_judge_need_review: Whether AI judge flagged for manual review
• llm_judge_improvement: AI judge improvement suggestions

User Information

• user: Complete user object with id, email, first_name, last_name
• reviewer: Reviewer user object (if conversation was reviewed)
• user_type: User permission level/type

Conversation Context

• agent_names: Array of AI agent names that participated
• ask_to_talk_to_human: Whether user requested human support
• tags: Array of conversation tags
• ticket_created: Whether a support ticket was generated

Messages (when include_messages=true)

When the include_messages parameter is set to true, each thread will include a messages array:

{
  "messages": [
    {
      "id": "message-uuid",
      "content": "Hello, I need help with my account",
      "role": "user",
      "answer_text": null,
      "thread": {
        "id": "thread-uuid",
        "title": "Account Help"
      },
      "knowledge_sources": [],
      "isStaff": false,
      "languages": ["en"],
      "agent": {
        "id": "agent-uuid",
        "name": "Customer Support AI"
      }
    },
    {
      "id": "message-uuid-2",
      "content": "I'd be happy to help you with your account.",
      "role": "assistant",
      "answer_text": "I'd be happy to help you with your account.",
      "thread": {
        "id": "thread-uuid",
        "title": "Account Help"
      },
      "knowledge_sources": [
        {
          "id": "source-uuid",
          "position": 1
        }
      ],
      "isStaff": false,
      "languages": ["en"],
      "agent": {
        "id": "agent-uuid",
        "name": "Customer Support AI"
      }
    }
  ]
}

• messages: Array of all messages in chronological order
• Each message includes agent information, knowledge sources, and role details
• Messages are optimized with efficient database queries to prevent performance issues

Usage Examples

Basic Request

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history" \
     -H "x-api-key: YOUR_API_KEY"

Filter by Date Range

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?start_date=2024-12-01T00:00:00Z&end_date=2024-12-07T23:59:59Z" \
     -H "x-api-key: YOUR_API_KEY"

Filter by User and Agent

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?email=[e-mail]&agent_name=Support%20AI" \
     -H "x-api-key: YOUR_API_KEY"

Filter Conversations Needing Review

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?need_review=true&evaluation=bad" \
     -H "x-api-key: YOUR_API_KEY"

Pagination Example

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?page=2" \
     -H "x-api-key: YOUR_API_KEY"

Include Messages in Response

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?include_messages=true" \
     -H "x-api-key: YOUR_API_KEY"

Combined Filtering with Messages

curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?evaluation=bad&include_messages=true&page=1" \
     -H "x-api-key: YOUR_API_KEY"

Error Responses

403 Forbidden

{
  "error": "Staff permissions required"
}

400 Bad Request

{
  "error": "Invalid date format"
}

Performance Considerations

• Pagination: Always use pagination for large datasets. Each page is limited to 50 items.
• Date Filtering: Use date filters to improve query performance on large datasets.
• Indexing: The API is optimized for filtering by date, user, and evaluation status.
• Caching: Consider implementing client-side caching for frequently accessed data.
• Message Inclusion: Using include_messages=true will increase response size and processing time. The feature uses optimized queries to prevent N+1 issues, but should be used judiciously for large datasets.