百宝箱开放平台 ✖️ 查询会话列表-阿里云开发者社区

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

2025-10-20 82

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： 本接口用于查询开放平台API或SDK发起的智能体会话列表，支持按应用、用户、渠道等条件分页筛选，需提前发布应用并获取访问令牌。

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

前提条件

在调用本接口前，请先完成应用的发布，若无，请参见：发布应用，完成相关事项。

请求地址

GEThttps://api.tbox.cn/api/conversation/conversations

请求头

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

请求参数

参数名	是否必填	类型	说明	示例
appId	是	String	应用 ID，需要通过 API 进行集成的应用 ID。获取方式可参见：获取AppID。	202506e******00450562
userId	否	String	用户ID，发起对话时指定，需要在智能体内唯一。不传返回全部用户的会话列表	test_user_zs
source	否	Enum<String>	对话渠道，用于筛选指定渠道的对话，不传值将返回所有渠道发生的会话动作。 AGENT_SDK：SDK 渠道 OPENAPI：OpenAPI 渠道 IOT_SDK：IOT SDK 渠道	AGENT_SDK
pageNum	否	Integer	分页页码，从 1 开始，默认为 1	1
pageSize	否	Integer	分页条数，默认为 10，最大 50	50
sortOrder	否	Enum<String>	会话列表排序方式，默认 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>	会话列表，列表内参数定义可参见：Conversation 定义。	-
traceId	String	traceId，用于排查问题	0a42******9262

Conversation 定义

参数名	类型	说明	示例
conversationId	String	会话ID	2025******0704
userId	String	用户ID	2023******0062
source	Enum<String>	会话所属渠道 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是否有效"
}