百宝箱开放平台 ✖️ 查询会话列表

查询会话列表

在开放平台， 会话是指用户与智能体的对话过程，可以包含多个轮次的问答。通过调用本接口，开发者可以查询由开放平台 API 或 SDK 发起的智能体会话列表。

前提条件

• 在调用本接口前，请先完成应用的发布。

请求地址

GET``https://api.tbox.cn/api/conversation/conversations

请求头

参数名	是否必填	类型	说明	示例
Authorization	是	String	用于验证客户端身份的访问令牌，你可以在百宝箱中获取，获取方式可参见：授权管理。	pat_2j4e******THUIVRH1

请求参数

参数名	是否必填	类型	说明	示例
appId	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	202506e******00450562
userId	否	String	用户ID，发起对话时指定，需要在智能体内唯一。不传返回全部用户的会话列表	test_user_zs
source	否	Enum	对话渠道，用于筛选指定渠道的对话，不传值将返回所有渠道发生的会话动作。- AGENT_SDK：SDK 渠道

• OPENAPI：OpenAPI 渠道
• IOT_SDK：IOT SDK 渠道 | AGENT_SDK | | pageNum | 否 | Integer | 分页页码，从 1 开始，默认为 1 | 1 | | pageSize | 否 | Integer | 分页条数，默认为 10，最大 50 | 50 | | sortOrder | 否 | Enum | 会话列表排序方式，默认 DESC- ASC： 按创建时间升序排序，最早创建的会话排在最前返回；
• DESC：按创建时间降序排序，最近创建的会话排在最前返回 | DESC |

请求示例

curl --location 'https://api.tbox.cn/api/conversation/conversations?appId={your_appId}&pageNum=1&pageSize=5' \
--header 'Authorization: {your_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ''

返回参数

通用参数

参数名	类型	说明	示例
errorCode	String	错误码，为 0 表示成功。	0
errorMsg	String	错误信息。	success
data	List	会话列表，列表内参数定义可参见：Conversation 定义。	-
traceId	String	traceId，用于排查问题	0a42******9262

Conversation 定义

参数名	类型	说明	示例
conversationId	String	会话ID	2025******0704
userId	String	用户ID	2023******0062
source	Enum	会话所属渠道- AGENT_SDK：SDK渠道

• OPENAPI：OpenAPI渠道
• IOT_SDK：IOT SDK 渠道 | AGENT_SDK | | createAt | Long | 会话创建时间（时间戳） | 1753953808 |

返回示例

成功返回

{
    "data": {
        "conversations": [
            {
                "conversationId": "2025******0704",
                "createAt": 1753953808,
                "source": "AGENT_SDK",
                "userId": "2023******0062"
            },
            {
                "conversationId": "2025******9615",
                "createAt": 1753356473,
                "source": "AGENT_SDK",
                "userId": "2023******0062"
            },
            {
                "conversationId": "2025******8076",
                "createAt": 1753355704,
                "source": "AGENT_SDK",
                "userId": "2023******0062"
            },
            {
                "conversationId": "2025******8485",
                "createAt": 1753355681,
                "source": "AGENT_SDK",
                "userId": "2023******0062"
            },
            {
                "conversationId": "2025******7930",
                "createAt": 1753355658,
                "source": "AGENT_SDK",
                "userId": "2023******00062"
            }
        ],
        "currentPage": 1,
        "pageSize": 5,
        "total": 71
    },
    "errorCode": "0",
    "errorMsg": "success",
    "traceId": "0a42******9262"
}

失败返回

{
    "errorCode": "P_1_02_084",
    "errorMsg": "app不存在",
    "solution": "请确认参数:appId是否有效"
}