對話

Quickchat AI 記錄所有通路的每段對話。這些端點可列出及取得對話。

Quickchat AI 會自動記錄並分析 AI Agent 在各通路的每段對話，包括 Widget、Slack、WhatsApp、Telegram 等。對話 API 提供程式化存取這些豐富資料的方式，可用於建立自訂控制台、提供下游分析流程資料、觸發 CRM 工作流程，或整合既有的商業智慧工具。

每段對話都包含 AI 分析：情緒偵測、主題分類、解決情況追蹤，以及對可能需要真人注意的對話進行自動標記。結合完整訊息歷史、連結點選追蹤與自訂中繼資料，您便具備瞭解訪客如何與 AI Agent 互動所需的資料。

對話資料分布於多個端點：

列出對話：基本資訊、訪客資料與狀態。適合控制台、總覽與篩選查詢
取得對話詳細資料：完整資訊，包括 unified_analysis（AI 產生的洞察）與 client_metadata
取得對話事件：完整訊息歷史、連結點選追蹤與記錄項目
取得/設定中繼資料：您附加至對話的自訂鍵值資料，請參閱對話中繼資料

列出對話

權限範圍：read_all

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

查詢參數

參數	說明
`limit` 整數	每頁項目數
`offset` 整數	要略過的項目數
`query` 字串	依序號、UUID 或訊息文字搜尋
`assignee_type` 字串	`"ai_assistant"`、`"human_operator"` 或 `"unassigned"`
`source` 字串	`"widget"`、`"slack"`、`"telegram"`、`"whatsapp"` 等
`resolution_status` 字串	`"open"` 或 `"resolved"`
`created_timestamp_start_date` 日期時間	依建立日期篩選（起始）
`created_timestamp_end_date` 日期時間	依建立日期篩選（結束）
`last_message_at_start_date` 日期時間	依最後訊息日期篩選（起始）
`last_message_at_end_date` 日期時間	依最後訊息日期篩選（結束）
`most_frequent_language` 字串	依偵測語言篩選
`order` 字串	`"desc"`（預設，最新優先）或 `"asc"`（最舊優先）。遞增順序適合從已知對話向後依序讀取，請搭配 `last_message_at_start_date`

Shell
Python

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

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()

回應 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
}

欄位	說明
`id` 字串	對話 UUID
`ord` 整數	對話流水號
`created_at` 字串	對話建立時間戳記
`last_message_at` 字串	最近一則訊息的時間戳記
`title` 字串	AI 產生的對話標題
`source` 字串	對話來源通路，例如 `"widget"`、`"slack"`、`"whatsapp"`
`terminated` 布林值	對話是否已結束
`resolution_status` 字串	`"open"` 或 `"resolved"`
`has_unread_messages` 布林值	是否有未讀訊息
`supports_inbox_control` 布林值	對話來源是否支援收件匣控制（指派、轉接）
`last_message_content` 字串	對話最後一則訊息的內容
`most_frequent_language` 字串	對話中最常偵測到的語言
`assignee` 物件	目前負責人（`type`：`"ai_assistant"`、`"human_operator"` 或 `"unassigned"`）
`visitor_name` 字串或 null	訪客姓名（來自聊天前表單或通路個人資料）
`visitor_email` 字串或 null	訪客電子郵件地址
`visitor_phone_number` 字串或 null	訪客電話號碼
`visitor_label` 字串或 null	指派給訪客的自訂標籤

取得對話詳細資料

權限範圍：read_all

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

Shell
Python

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

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()

回應 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
}

詳細資料回應包含清單回應的所有欄位，另外還有：

欄位	說明
`url` 字串或 null	開始對話的頁面 URL（僅 Widget）
`client_metadata` 物件或 null	附加至對話的自訂鍵值組
`last_visitor_message_at` 字串	訪客最後一則訊息的時間戳記
`unified_analysis` 物件或 null	AI 產生的對話分析（見下方）

unified_analysis 欄位：

欄位	說明
`sentiment` 字串	AI 偵測的對話情緒，例如 `"positive"`、`"neutral"`、`"negative"`
`resolution_status` 字串	AI 評估的解決狀態（可能與頂層 `resolution_status` 不同）
`topic` 字串	AI 偵測的對話主題
`is_flagged` 布林值	AI 是否標記此對話供真人檢閱
`flag_reason` 字串或 null	標記對話的原因

頂層 resolution_status 欄位（"open" 或 "resolved"）是手動或自動化規則設定的正式狀態。

unified_analysis.resolution_status 由 AI 分析計算，可能不同。例如頂層狀態仍為 "open"，但 AI 根據內容判斷對話已解決。篩選與工作流程請使用頂層欄位；分析與洞察請使用 unified_analysis。

取得對話事件

取得對話的所有事件，包括訊息、追蹤連結與記錄。

權限範圍：read_all

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

查詢參數

參數	說明
`limit` 整數	每頁項目數
`offset` 整數	要略過的項目數

Shell
Python

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

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()

回應 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
}

事件類型： message、tracked_link、log

作者類型： ai_assistant、visitor、human_operator

欄位	說明
`type` 字串	事件類型：`"message"`、`"tracked_link"` 或 `"log"`
`data.id` 字串	訊息唯一識別碼
`data.ord` 整數	訊息流水號
`data.created_at` 字串	事件時間戳記
`data.content` 字串	訊息內容
`data.author` 字串	`"ai_assistant"`、`"visitor"` 或 `"human_operator"`
`data.handoff_state` 字串或 null	轉接狀態（若適用）
`data.message_insights` 物件或 null	AI 產生的訊息洞察
`data.feedback` 物件或 null	使用者對訊息的意見
`data.client_metadata` 物件或 null	附加至訊息的自訂中繼資料
`data.sources_generated` 陣列	AI 產生回覆時使用的知識庫文章
`data.is_welcome` 布林值	是否為歡迎訊息
`data.attachments` 陣列	檔案附件

對話

列出對話

取得對話詳細資料

取得對話事件

開始使用

AI Agent

Actions

對話

Channels

您的網站

Helpdesk 與 CRM

通訊應用程式

帳戶與帳務

開始使用

設定

Knowledge Base

對話