Conversations History API - AGO Documentation

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.

Automatically import completed external conversations

When your external chatbot closes a conversation, send its complete text transcript to POST /api/v1/conversations/import. The external system handles collection, normalization, and delivery; AGO stores the transcript and runs the enabled quality/CX and topic analyses in the background, including for historical conversations. Use an API key with conversations:write. Configure an AGO agent to represent your external chatbot and provide its ID on every import. Its instructions provide context for the analysis; importing does not run the chatbot or execute its tools. Enable the Thread Evaluator and Topic Analyzer in AGO to run those analyses.

curl -X POST 'https://<your-tenant-api>/api/v1/conversations/import' \
  -H 'X-API-Key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "support-bot",
    "external_id": "conversation-123",
    "agent_id": "00000000-0000-0000-0000-000000000001",
    "user": {"external_id": "customer-456"},
    "title": "Order tracking",
    "messages": [
      {"role": "user", "content": "Where is my order?", "created_at": "2026-09-01T10:00:00Z"},
      {"role": "assistant", "content": "It arrives tomorrow.", "created_at": "2026-09-01T10:00:05Z"}
    ]
  }'

source, external_id, agent_id, user.external_id, and messages are required; title is optional. Source names use lowercase letters, digits, dots, underscores, or hyphens, start with a letter or digit, and are at most 100 characters. External IDs are at most 255 characters. Participants are identified within each source and do not need an AGO login. Messages must contain nonblank text, use user or assistant, and include dates with a timezone. Include at least one message of each role in chronological order. Equal dates retain the supplied order. A request accepts at most 1,000 messages, 100,000 characters per message, and 1 MB of normalized JSON. Unsupported fields, attachments, and tool traces are rejected; no content is silently truncated.

Delivery, retries, and results

201: stored successfully. The response contains the AGO conversation id and provenance, including the source, external ID, reception time, and separate analyses.evaluation and analyses.topics statuses.
200: the same transcript was already imported. AGO returns the same ID. Completed analyses are preserved; failed analyses or previously disabled analyses that are now enabled can be queued again.
409: this source and external ID already identify a different transcript. AGO leaves the existing conversation unchanged. Transcripts cannot be appended to or replaced.

After a network timeout or transient server error, retry the exact same payload with a backoff. Identity is unique within the tenant and source, so repeated deliveries cannot create duplicate conversations. Do not change the IDs between retries. Correct validation errors before retrying. Read GET /api/v1/conversations/{id} with conversations:read (or conversations:write) to retrieve the transcript, topics, cx_score, cx_score_data, provenance, and read_only. Each analysis status is pending, running, completed, failed, or disabled. Analysis failures receive three automatic retries with increasing delays. Interrupted work and queue delivery failures are recovered automatically by a daily sweep; the initial HTTP response does not wait for analysis completion. A failed status includes an error_code without exposing provider credentials or transcript contents.

Filter by provenance

The public conversation list and export, internal history API, and dashboard analytics accept conversation_source:

Value	Conversations included
Omitted	All conversations
`ago`	Conversations originating in AGO, including its native integrations
`import:support-bot`	Conversations imported with `source: "support-bot"`

GET /api/v1/conversations/import-sources lists the available external sources. This filter is separate from the browser-origin filter. Dates in reports reflect the original transcript, not the day it was imported. Import participant profiles do not count as new AGO registrations. Imported conversations appear in the existing review screens. Their transcripts are read-only; administrators can still evaluate them, add comments, and manage labels. Imports do not include tool usage, generation costs, latency, tickets, or declared satisfaction data.

API Endpoint

GET /api/business_messages/all-threads-history

Authentication: Requires Admin, Account Manager, or Viewer access.

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. This example shows a selection of its fields:

{
  "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": "OK",
      "llm_judge_evaluated": true,
      "llm_judge_need_review": false,
      "llm_judge_improvement": "No improvements needed",
      "user": {
        "id": "user-uuid",
        "email": "user@example.com",
        "first_name": "John",
        "last_name": "Doe"
      },
      "reviewer": {
        "id": "reviewer-uuid",
        "email": "admin@example.com",
        "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 (OK, KO, NEUTRAL, or NOT_EVALUATED)
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 includes a messages array. For example:

{
  "messages": [
    {
      "id": "message-uuid",
      "content": "Hello, I need help with my account",
      "role": "user",
      "knowledge_sources": [],
      "isStaff": false,
      "languages": ["en"],
      "agent": "00000000-0000-0000-0000-000000000001",
      "routed_from_agent": null,
      "attachments": []
    },
    {
      "id": "message-uuid-2",
      "content": "I'd be happy to help you with your account.",
      "role": "assistant",
      "knowledge_sources": [
        {
          "id": "source-uuid",
          "position": 1
        }
      ],
      "isStaff": false,
      "languages": ["en"],
      "agent": "00000000-0000-0000-0000-000000000001",
      "routed_from_agent": null,
      "attachments": []
    }
  ]
}

messages: Array of all messages in chronological order
Each message includes agent information, knowledge sources, and role details

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=user@example.com&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=KO" \
     -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=KO&include_messages=true&page=1" \
     -H "x-api-key: YOUR_API_KEY"

Error Responses

403 Forbidden

{
  "error": "Forbidden: Admin or account manager access required"
}

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.
Caching: Consider implementing client-side caching for frequently accessed data.
Message Inclusion: Using include_messages=true will increase response size and processing time. Use it when you need the transcript contents.

​Automatically import completed external conversations

​Delivery, retries, and results

​Filter by provenance

​API Endpoint

​Overview

​Request Parameters

​Date Filtering

​User Filtering

​Conversation Content

​Conversation Status

​Knowledge Base

​Pagination

​Message Data

​Response Format

​Response Fields

​Thread Information

​Evaluation & Quality

​User Information

​Conversation Context

​Messages (when include_messages=true)

​Usage Examples

​Basic Request

​Filter by Date Range

​Filter by User and Agent

​Filter Conversations Needing Review

​Pagination Example

​Include Messages in Response

​Combined Filtering with Messages

​Error Responses

​403 Forbidden

​Performance Considerations

Automatically import completed external conversations

Delivery, retries, and results

Filter by provenance

API Endpoint

Overview

Request Parameters

Date Filtering

User Filtering

Conversation Content

Conversation Status

Knowledge Base

Pagination

Message Data

Response Format

Response Fields

Thread Information

Evaluation & Quality

User Information

Conversation Context

Messages (when `include_messages=true`)

Usage Examples

Basic Request

Filter by Date Range

Filter by User and Agent

Filter Conversations Needing Review

Pagination Example

Include Messages in Response

Combined Filtering with Messages

Error Responses

403 Forbidden

Performance Considerations