Obtaining AI Chat Responses

This document will guide developers on how to obtain the AI response content in a specified chat session via an API, including message text, generated data tables, and relevant metadata.

📌 Scenario Explanation

When users send questions to the chatbot, the system will return the AI's answer along with its generated data analysis results (such as tables, charts). To retrieve these response contents, you need to call the following two APIs:

1. Get all messages in a chat (including human and AI)
2. Get the associated DataFrame for a specific message

---

✅ Step 1: Retrieve the List of Chat Messages

Interface Description

GET /v1/chats/{chat_id}/messages

Parameter Description

Parameter Name	Type	Description
chat_id	string	Chat ID (required)
page	integer	Page number, default is 1
size	integer	Number of items per page, default is 50

Example Request

GET https://api.asktable.com/v1/chats/chat_1kZOsPmqa5bOp7NU5cr6qg/messages
Authorization: Bearer <your_token>

Example Response

{
  "items": [
    {
      "id": "msg_17xgEdEk0NDJ6PSjEi9BDh",
      "role": "human",
      "content": {
        "text": "Provincial GDP statistics"
      }
    },
    {
      "id": "msg_1aMWDT8jPvxXiKw2UPHh2i",
      "role": "ai",
      "content": {
        "text": "According to the query results, the provincial GDP statistics are as follows: ..."
      },
      "dataframe_ids": ["df_2YI69gN3UQRKGy0cD0kEce"]
    }
  ],
  "total": 2
}

Explanation:
In the returned result, the role: "ai" is the AI response, and the field content.text is the text content;
If the message generates analytical results, the dataframe_ids will include the corresponding DataFrame ID.

---

✅ Step 2: Obtain the Details of the AI-generated DataFrame

Interface Description

GET /v1/dataframes/{dataframe_id}

Parameter Description

Parameter Name	Type	Description
dataframe_id	string	ID from the AI message

Example Request

GET https://api.asktable.com/v1/dataframes/df_2YI69gN3UQRKGy0cD0kEce
Authorization: Bearer <your_token>

Example Response

{
  "title": "GDP Statistics",
  "sql": "SELECT ... ORDER BY \"GDP_万亿\" DESC",
  "header": [
    { "key": "province", "label": "Province" },
    { "key": "gdp", "label": "GDP Total (trillion CNY)" },
    { "key": "population", "label": "Population (ten thousand)" },
    { "key": "area", "label": "Area (ten thousand square kilometers)" }
  ],
  "content": [
    { "province": "Guangdong", "gdp": 9.73, "population": 11346, "area": 17.97 },
    { "province": "Jiangsu", "gdp": 9.26, "population": 8051, "area": 10.72 }
  ],
  "chart_options": {
    "bar": { "xAxisKey": "province", "columns": [{ "key": "gdp", "label": "GDP" }] },
    "pie": { "nameKey": "province", "columns": [{ "key": "gdp", "label": "GDP" }] },
    "default": "bar"
  }
}

Explanation:

• title represents the name of the data table
• sql is the generated query statement
• content is a preview of the first few rows of the query results
• chart_options provides recommended visualization methods (e.g., bar chart, pie chart)

---

🧩 Example Display

When the user asks: “Provincial GDP statistics,” the AI message returned by the system is as follows:

• Text response:

  According to the query results, the provincial GDP statistics are as follows:
  1. Guangdong Province: GDP is 9.73 trillion CNY, population is 113.46 million...
• Data analysis result:

  {
    "province": "Guangdong",
    "gdp": 9.73,
    "population": 11346,
    "area": 17.97
  }

You can use this data to generate charts or embed it in a frontend display.

---

🛠️ Summary

Step	API Call
Get Message List	GET /v1/chats/{chat_id}/messages
Get Data Details	GET /v1/dataframes/{dataframe_id}

---

If further integration is needed, you can also use POST /v1/chats/{chat_id}/messages to send questions and get new responses, see "Question Sending Interface Documentation".

Do you need me to write a Markdown version or an English version for you?