获取会话列表

合并查询指定用户的 Open API 与已授权绑定设备会话，默认只返回有效会话。

注意

user_id 与 device_id 配合：user_id 限定会话归属用户（含该用户绑定的设备会话），device_id 可进一步限定到具体设备；两者配合即可查询某用户某设备的会话与消息。

请求信息

请求 URI

GET https://lg.jimitu.top/api/open/sessions

请求头参数

请求头	必填	说明
`Authorization`	是	Bearer {API Key}，接口鉴权，所有请求均需携带
`Content-Type`	否	仅 POST/PUT 携带 JSON 请求体时需要，值为 application/json

请求查询参数

参数	类型	必填	说明
user_id	string	是	设备绑定的外部用户 ID
character_id	integer	否	限定角色
session_source	string	否	`all`（默认）/ `open_api` / `device`
channel_id	integer	否	限定硬件渠道
device_id	string	否	限定设备 ID
product_key	string	否	配合设备 ID 消歧产品型号
include_expired	boolean	否	true 时含自动失效会话
include_inactive	boolean	否	true 时含手动关闭会话
page	integer	否	页码，默认 1
page_size	integer	否	每页条数，默认 20，最大 100

注意

character_id、channel_id、page、page_size 格式错误或超分页上限 → 400 INVALID_QUERY_PARAMETER。

请求示例

curl -X GET "https://lg.jimitu.top/api/open/sessions?user_id=<user_id>&page=1&page_size=20" \
  -H "Authorization: Bearer <your_api_key>"

响应信息

响应体示例

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "name": "open_api_小叽_<user_id>",
      "session_source": "device",
      "character_id": 555,
      "character_name": "小叽",
      "user_id": "<user_id>",
      "publishing_id": 1,
      "channel_id": 100,
      "device_id": "123456",
      "product_key": "...",
      "is_active": true,
      "is_expired": false,
      "message_count": 42,
      "last_message_at": "2026-01-01T12:00:00Z",
      "expired_at": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 3, "total_count": 58, "has_next": true, "has_previous": false }
}

响应参数

字段	类型	说明
id	integer	会话 ID
name	string	会话名（自动生成：open_api_{角色名}_{user_id}）
session_source	string	`open_api`=APP 会话 / `device`=硬件网关会话
character_id	integer	角色实例 ID
character_name	string	角色名称
user_id	string	外部用户 ID
publishing_id	integer	硬件会话有；APP 会话为 null
channel_id	integer	硬件会话有；APP 会话为 null
device_id	string	硬件会话有；APP 会话为 null
product_key	string	硬件会话有；APP 会话为 null
is_active	boolean	false=已手动关闭
is_expired	boolean	true=已自动失效（>24h 或 >5000 条）
message_count	integer	消息条数
last_message_at	string	最后消息时间
expired_at	string/null	失效时间
created_at	string	创建时间
updated_at	string	更新时间

错误码

error_code	状态码	说明
`INVALID_QUERY_PARAMETER`	400	查询参数格式错误或超分页上限

其他

会话状态说明

is_active	is_expired	含义	默认是否返回
true	false	有效会话，可正常发消息	✅ 是
true	true	自动失效，不可发消息	❌ 需 include_expired=true
false	false	手动关闭，不可发消息	❌ 需 include_inactive=true
false	true	关闭且已失效	❌ 两个参数均需 true

获取会话列表 ​

请求信息

请求 URI

请求头参数

请求查询参数

请求示例

响应信息

响应体示例

响应参数

错误码

错误码

其他

会话状态说明

获取会话列表