Conversations

Quickchat AI automatically captures and analyzes every conversation your AI Agent has across all channels — widget, Slack, WhatsApp, Telegram, and more. The Conversations API gives you programmatic access to this rich dataset for building custom dashboards, feeding downstream analytics pipelines, triggering CRM workflows, or integrating with your existing business intelligence tools.

Every conversation includes AI-powered analysis: sentiment detection, topic classification, resolution tracking, and automatic flagging of conversations that may need human attention. Combined with full message history, tracked link clicks, and custom metadata, you have everything you need to understand how visitors interact with your AI Agent.

Conversation data is spread across several endpoints:

• List Conversations — Basic info, visitor details, status. Use for dashboards, overviews, and filtered queries
• Get Conversation Details — Full info including unified_analysis (AI-generated insights) and client_metadata
• Get Conversation Events — Complete message history, tracked link clicks, and log entries
• Get/Set Metadata — Custom key-value data you attach to conversations (see Conversation Metadata)

List Conversations

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip
query string	Search by order number, UUID, or message text
assignee_type string	"ai_assistant", "human_operator", or "unassigned"
source string	"widget", "slack", "telegram", "whatsapp", etc.
resolution_status string	"open" or "resolved"
created_timestamp_start_date datetime	Filter by creation date (start)
created_timestamp_end_date datetime	Filter by creation date (end)
last_message_at_start_date datetime	Filter by last message date (start)
last_message_at_end_date datetime	Filter by last message date (end)
most_frequent_language string	Filter by detected language

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "resolution_status": "open"},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "id": "conv-uuid-1234",
      "ord": 42,
      "created_at": "2026-01-15T10:30:00Z",
      "last_message_at": "2026-01-15T10:35:00Z",
      "title": "Return policy question",
      "source": "widget",
      "terminated": false,
      "resolution_status": "open",
      "has_unread_messages": true,
      "supports_inbox_control": true,
      "last_message_content": "What is your return policy?",
      "most_frequent_language": "en",
      "assignee": {
        "type": "ai_assistant"
      },
      "visitor_name": "John",
      "visitor_email": "john@example.com",
      "visitor_phone_number": null,
      "visitor_label": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 42
}

Field	Description
id string	Conversation UUID
ord integer	Sequential conversation number
created_at string	Conversation creation timestamp
last_message_at string	Timestamp of the most recent message
title string	AI-generated conversation title
source string	Channel the conversation originated from (e.g., "widget", "slack", "whatsapp")
terminated boolean	Whether the conversation has ended
resolution_status string	"open" or "resolved"
has_unread_messages boolean	Whether there are unread messages
supports_inbox_control boolean	Whether the conversation source supports inbox control (assign, handoff)
last_message_content string	Content of the last message in the conversation
most_frequent_language string	Most frequently detected language in the conversation
assignee object	Current assignee (type: "ai_assistant", "human_operator", or "unassigned")
visitor_name string or null	Visitor’s name (from pre-chat form or channel profile)
visitor_email string or null	Visitor’s email address
visitor_phone_number string or null	Visitor’s phone number
visitor_label string or null	Custom label assigned to the visitor

Get Conversation Details

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "id": "conv-uuid-1234",
  "ord": 42,
  "created_at": "2026-01-15T10:30:00Z",
  "last_message_at": "2026-01-15T10:35:00Z",
  "title": "Return policy question",
  "source": "widget",
  "terminated": false,
  "resolution_status": "open",
  "has_unread_messages": true,
  "supports_inbox_control": true,
  "last_message_content": "What is your return policy?",
  "most_frequent_language": "en",
  "assignee": {
    "type": "ai_assistant"
  },
  "url": null,
  "client_metadata": {"userId": 12},
  "last_visitor_message_at": "2026-01-15T10:34:00Z",
  "unified_analysis": {
    "sentiment": "neutral",
    "resolution_status": "open",
    "topic": "Return policy",
    "is_flagged": false,
    "flag_reason": null
  },
  "visitor_name": "John",
  "visitor_email": "john@example.com",
  "visitor_phone_number": null,
  "visitor_label": null
}

The detail response includes all fields from the list response, plus:

Field	Description
url string or null	URL of the page where the conversation started (widget only)
client_metadata object or null	Custom key-value pairs attached to the conversation
last_visitor_message_at string	Timestamp of the last visitor message
unified_analysis object or null	AI-generated analysis of the conversation (see below)

unified_analysis fields:

Field	Description
sentiment string	AI-detected conversation sentiment (e.g., "positive", "neutral", "negative")
resolution_status string	AI-assessed resolution status (may differ from top-level resolution_status)
topic string	AI-detected conversation topic
is_flagged boolean	Whether the AI flagged this conversation for human review
flag_reason string or null	Reason the conversation was flagged

resolution_status vs unified_analysis.resolution_status

The top-level resolution_status field ("open" or "resolved") is the canonical status set manually or by automation rules.

The unified_analysis.resolution_status is computed by AI analysis and may differ — for example, the AI might classify a conversation as resolved based on content analysis even though the top-level status is still "open". Use the top-level field for filtering and workflow; use unified_analysis for analytics and insights.

Get Conversation Events

Retrieve all events (messages, tracked links, logs) for a conversation.

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 20},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-001",
        "ord": 1,
        "created_at": "2026-01-15T10:30:00Z",
        "content": "Hello! How can I help you today?",
        "author": "ai_assistant",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": true,
        "attachments": []
      }
    },
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-002",
        "ord": 2,
        "created_at": "2026-01-15T10:31:00Z",
        "content": "What is your return policy?",
        "author": "visitor",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": false,
        "attachments": []
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 2
}

Event types: message, tracked_link, log

Author types: ai_assistant, visitor, human_operator

Field	Description
type string	Event type: "message", "tracked_link", or "log"
data.id string	Message unique identifier
data.ord integer	Sequential message number
data.created_at string	Timestamp of the event
data.content string	Message content
data.author string	"ai_assistant", "visitor", or "human_operator"
data.handoff_state string or null	Handoff state if applicable
data.message_insights object or null	AI-generated message insights
data.feedback object or null	User feedback on the message
data.client_metadata object or null	Custom metadata attached to the message
data.sources_generated array	Knowledge Base articles the AI used when generating its response
data.is_welcome boolean	Whether this is a welcome message
data.attachments array	File attachments

---