帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>智能客服（Desk）>工作台接入>SDK 集成>Web 集成>AIDeskCore>会话相关

会话相关

最近更新时间：2026-08-13 16:20:00
我的收藏

本页目录：

消息类介绍

AIDeskCore 中的会话为 ISessionModel 类型，会话分为四种：
IM ：表示客服之间与客服与外部用户之间的会话。
ROBOT：表示外部客户在与机器人聊天阶段的会话。
IM_QUEUE：表示外部客户已转人工在排队等待分配阶段的会话。
IM_OTHER_INPROGRESS：表示外部客户转人工成功在与客服聊天阶段的会话。
type IMSession = {
    /** 会话 ID。 */
    sessionId: string;
    /** 会话类型。 */
    type: SESSION_TYPE.IM;
    /** 会话用户端的用户 ID。 */
    userId: string;
    /** 会话用户端的用户头像。 */
    avatar: string;
    /** 会话用户端的用户昵称。 */
    nickname: string;
    /** 会话创建时间戳。 */
    timestamp: number;
    /** 网站渠道自定义数据。 */
    clientData: string;
    /** 会话最后一条消息。 */
    lastMessage?: IMessageModel;
    /** 未读消息数。 */
    unreadCount: number;
    /** 用户端来源。 */
    peerSource: string;
    /** 会话呼入超时时间，用于提示会话接入消息。 */
    timeout: number;
    /** 是否为内部会话。 */
    isInnerSession: boolean;
    /** 接入客服 ID。 */
    channelAgentID: string;
    /** 是否为主动联系。 */
    isIMCallOut?: number;
    /** 会话状态。 */
    sessionState: SessionState; // 'ringing' | 'inProgress' | 'finished' | 'seatJoining' | ''
    /** IM 会话是否为群聊。 */
    imAgentChatType?: number;
    /** 接入客服号名称。 */
    channelName?: string;
    /** 超时未回复时间。 */
    IMReplyTimeOut?: number;
    /** 会话语言。 */
    language?: string;
    /** 会话国家。 */
    country?: string;
    /** 会话时区。 */
    timezone?: string;
    /** 群人数，仅群组会话具有。 */
    groupMemberNum?: number;
    /** 会话标记状态。 */
    starStatus?: number;
    /** 用户备注。 */
    remark?: string;
    /** 用户 IP。 */
    userClientIP?: string;
    /** 客服技能组 ID。 */
    skillGroupId?: string;
    /** 客服工号。 */
    staffNo?: string;
    /** 网站渠道用户在线状态。 */
    userStatus: '1' | '2';
    /** 用户在 src 为 7 时的自定义数据。 */
    clientCustomData?: string;
    /** 子会话 ID。 */
    subSessionId?: string;
    /** 子会话序号。 */
    subSessionNumber?: number;
    /** 草稿。 */
    draft: string;
    /** 用户黑名单信息。 */
    userBlacklist?: {
        /** 黑名单开始时间。 */
        startTime: number;
        /** 黑名单结束时间。 */
        endTime: number;
        /** 拉黑类型。 */
        blockType: number;
        /** 拉黑原因。 */
        reason: string;
    };
};
type RobotSession = {
    /** 会话 ID。 */
    sessionId: string;
    /** 会话类型。 */
    type: SESSION_TYPE.ROBOT;
    /** 会话用户端的用户 ID。 */
    userId: string;
    /** 当前会话的群 ID。 */
    groupID: string;
    /** 会话用户端的用户头像。 */
    avatar: string;
    /** 会话用户端的用户昵称。 */
    nickname: string;
    /** 会话创建时间戳。 */
    timestamp: number;
    /** 网站渠道自定义数据。 */
    clientData: string;
    /** 会话最后一条消息。 */
    lastMessage?: IMessageModel;
    /** 用户端来源。 */
    peerSource: string;
    /** 接入客服 ID。 */
    channelAgentID: string;
    /** IM 会话是否为群聊。 */
    imAgentChatType?: number;
    /** 接入客服号名称。 */
    channelName?: string;
    /** 会话语言。 */
    language?: string;
    /** 群人数，仅群组会话具有。 */
    groupMemberNum?: number;
    /** 用户备注。 */
    userMark?: string;
    /** 用户 IP。 */
    userClientIP?: string;
    /** 转人工次数。 */
    transToAgentTimes: number;
    /** 用户在 src 为 7 时的自定义数据。 */
    clientCustomData?: string;
    /** 子会话 ID。 */
    subSessionId?: string;
    /** 子会话序号。 */
    subSessionNumber?: number;
    /** 转人工状态。 */
    transferStatus: string;
};
type QueueSession = {
    /** 会话 ID。 */
    sessionId: string;
    /** 会话类型。 */
    type: SESSION_TYPE.IM_QUEUE;
    /** 会话用户端的用户 ID。 */
    userId: string;
    /** 当前会话的群 ID。 */
    groupID: string;
    /** 会话用户端的用户头像。 */
    avatar: string;
    /** 会话用户端的用户昵称。 */
    nickname: string;
    /** 会话创建时间戳。 */
    timestamp: number;
    /** 网站渠道自定义数据。 */
    clientData: string;
    /** 会话最后一条消息。 */
    lastMessage?: IMessageModel;
    /** 用户端来源。 */
    peerSource: string;
    /** 接入客服 ID。 */
    channelAgentID: string;
    /** IM 会话是否为群聊。 */
    imAgentChatType?: number;
    /** 接入客服号名称。 */
    channelName?: string;
    /** 会话语言。 */
    language?: string;
    /** 群人数，仅群组会话具有。 */
    groupMemberNum?: number;
    /** 用户备注。 */
    userMark?: string;
    /** 用户 IP。 */
    userClientIP?: string;
    /** 会话状态。 */
    currentState: string;
    /** 用户在 src 为 7 时的自定义数据。 */
    clientCustomData?: string;
    /** 子会话 ID。 */
    subSessionId?: string;
    /** 子会话序号。 */
    subSessionNumber?: number;
};
type IMOtherInprogressSession = {
    /** 会话 ID。 */
    sessionId: string;
    /** 会话类型。 */
    type: SESSION_TYPE.IM_OTHER_INPROGRESS;
    /** 会话用户端的用户 ID。 */
    userId: string;
    /** 当前会话的群 ID。 */
    groupID: string;
    /** 会话用户端的用户头像。 */
    avatar: string;
    /** 会话用户端的用户昵称。 */
    nickname: string;
    /** 会话创建时间戳。 */
    timestamp: number;
    /** 网站渠道自定义数据。 */
    clientData: string;
    /** 会话最后一条消息。 */
    lastMessage?: IMessageModel;
    /** 用户端来源。 */
    peerSource: string;
    /** 接入客服 ID。 */
    channelAgentID: string;
    /** IM 会话是否为群聊。 */
    imAgentChatType?: number;
    /** 接入客服号名称。 */
    channelName?: string;
    /** 会话语言。 */
    language?: string;
    /** 群人数，仅群组会话具有。 */
    groupMemberNum?: number;
    /** 用户备注。 */
    userMark?: string;
    /** 用户 IP。 */
    userClientIP?: string;
    /** 当前接入的客服 ID。 */
    currentStaff: string;
    /** 当前接入的客服昵称。 */
    currentStaffNickName: string;
    /** 坐席状态。 */
    seatStatus: string;
    /** 休息原因。 */
    restReason: string;
    /** 会话结束类型：1 表示转接，2 表示结束。 */
    memberOutType: number;
    /** 用户在 src 为 7 时的自定义数据。 */
    clientCustomData?: string;
    /** 子会话 ID。 */
    subSessionId?: string;
    /** 子会话序号。 */
    subSessionNumber?: number;
};
说明：
座席之间的单聊会话默认保存30天。
已转人工成功外部用户的会话的有效期为 24小时 ，请在24小时内处理完会话信息。

会话相关 API

切换当前活跃会话

调用此 API 会切换 AIDeskCore 存储层当前选择的会话。
接口
AIDeskCoreInstance.sessionService.switchSession(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
sessionId
string
-
会话的 ID。
sessionType
string
-
会话类型。
返回值
无
示例
enum SESSION_TYPE {
  IM = 'im',
  ROBOT = 'im_robot',
  IM_QUEUE = 'im_queue',
  IM_OTHER_INPROGRESS = 'im_other_inprogress',
}

import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.switchSession({ sessionId: 'sessionId', sessionType: SESSION_TYPE });

接听会话

调用此 API 会 接听状态为 ringing 的会话。
接口
AIDeskCoreInstance.sessionService.acceptSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要接听的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.acceptSession(sessionId);

结束会话

调用此 API 会结束状态为 inProgress 的会话。
接口
AIDeskCoreInstance.sessionService.endSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要结束的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.endSession(sessionId);

完成会话

调用此 API 会将状态为 finished 的会话移除会话列表。
接口
AIDeskCoreInstance.sessionService.completeSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要完成服务的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.completeSession(sessionId);

下发会话满意度评价

调用此 API 在状态为 inProgress 会话中下发满意度评价消息。
接口
AIDeskCoreInstance.sessionService.evaluateSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要下发评价消息的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.evaluateSession(sessionId);

会话标记未读

调用此 API 会将状态为 inProgress 会话的未读数从 0 变成 1。
接口
AIDeskCoreInstance.sessionService.markSessionUnread(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要标记未读的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.markSessionUnread(sessionId);

会话标记

调用此 API 会将状态为 inProgress 会话做一个 mark 标记，改变会话 starStatus 的属性，且此操作会让会话不受自动超时结束影响。
接口
AIDeskCoreInstance.sessionService.markSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
需要标记的会话 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

AIDeskCoreInstance.sessionService.markSession(sessionId);

获取客服列表信息

调用此 API 可查询当前应用下客服的信息。
接口
AIDeskCoreInstance.sessionService.getStaffList(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
pageNum
number
-
分页号。
pageSize
number
-
分页大小。
isNeedStatus
boolean
-
是否返回客服状态。
skillGroupType
number
-
客服分组类型。
fuzzingKeyWord
string
-
查询关键词。
返回值
Promise<object>
返回值为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
total
number
-
所有数据的条数。
staffList
object[]
-
客服数据列表。
staffList 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
userId
string
-
客服的账号。
nickName
string
-
客服昵称。
avatar
string
-
客服头像。
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.getStaffList(options);

获取客服分组列表信息

调用此 API 可查询当前应用下客服分组的信息。
接口
AIDeskCoreInstance.sessionService.getSkillGroupList(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
pageNum
number
-
分页号。
pageSize
number
-
分页大小。
skillGroupType
number
-
客服分组类型。
fuzzingKeyWord
string
-
查询关键词。
返回值
Promise<object>
返回值为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
total
number
-
所有数据的条数。
skillGroupList
object[]
-
客服分组数据列表。
skillGroupList 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
freeCntExceptReqMember
number
-
分组空闲人数。
skillGroupName
string
-
客服分组昵称。
skillGroupId
string
-
客服分组 ID。
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.getSkillGroupList(options);

转接会话

调用此 API 可将状态为 inProgress 的会话转接到指定客服或分组。
接口
AIDeskCoreInstance.sessionService.transferSession(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
sessionId
string
-
需要转接的会话 ID。
userId
string
-
客服 ID。
skillGroupId
string
-
客服分组 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

// userId或skillGroupId填入一个即可
const result = await AIDeskCoreInstance.sessionService.getSkillGroupList(options);

咨询入口查询

调用此 API 可查询用于主动联系的 IM 咨询入口列表。
接口
AIDeskCoreInstance.sessionService.getIMAgentList();
参数
无
返回值
Promise<object>
返回值为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
userId
number
-
咨询入口的 ID。
nickName
string
-
咨询入口昵称。
avatar
string
-
咨询入口头像。
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.getIMAgentList();

主动联系 IM 用户的资料查询

调用此 API 可查询用于主动联系的 IM 用户信息。
接口
AIDeskCoreInstance.sessionService.getIMUserProfile(userIDs);
参数
参数
类型
默认值
描述
userIDs
string[]
-
IM 应用下的 userid 列表。
返回值
Promise<object>
返回值为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
userId
number
-
用户的 ID。
nickName
string
-
用户的昵称。
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.getIMUserProfile(['1']);

主动联系 IM 用户发起会话

调用此 API 可查询用于主动联系的 IM 用户发起外部会话。
接口
AIDeskCoreInstance.sessionService.followUpSession(ClientUserID, channelAgentID, peerSource, IgnoreReceptionLimit);
参数
参数
类型
默认值
描述
ClientUserID
string
-
联系的 IM 用户 ID。
channelAgentID
string
-
咨询入口 ID。
peerSource
string ｜ undefined
-
用户来源。
IgnoreReceptionLimit
number ｜ undefined
-
是否忽略接待上限。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.followUpSession(
    'ClientUserID',
    'channelAgentID',
    '4',
    1
)

主动介入机器人会话

调用此 API 可直接让客户结束机器人阶段的会话并转入当前客服。
接口
AIDeskCoreInstance.sessionService.takeoverRobotSession(clientUserID, channelAgentID, peerSource);
参数
参数
类型
默认值
描述
clientUserID
string
-
主动联系的用户 ID。
channelAgentID
string
-
咨询入口 ID。
peerSource
string ｜ undefined
-
用户来源。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.takeoverRobotSession(
    'ClientUserID',
    'channelAgentID',
    '4',
)

主动介入排队中会话

调用此 API 可直接让客户结束会话的排队阶段并转入当前客服。
接口
AIDeskCoreInstance.sessionService.takeOverIMQueueSession(clientUserID, channelAgentID, peerSource);
参数
参数
类型
默认值
描述
clientUserID
string
-
主动联系的用户 ID。
channelAgentID
string
-
咨询入口 ID。
peerSource
string ｜ undefined
-
用户来源。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.takeOverIMQueueSession(
    'ClientUserID',
    'channelAgentID',
    '4',
)

介入进行中的会话

调用此 API 可私聊当前接待会话的客服，并将客服与用户的最近 20 条消息作为合并消息发送到客服单聊中。
接口
AIDeskCoreInstance.sessionService.interveneOtherSeatInprogressSession(sessionId);
参数
参数
类型
默认值
描述
sessionId
string
-
会话的 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.interveneOtherSeatInprogressSession(sessionId);

隐藏内部会话

调用此 API 可将客服之间的聊天隐藏。
接口
AIDeskCoreInstance.sessionService.hideInnerSessions(sessionIDList);
参数
参数
类型
默认值
描述
sessionIDList
string[]
-
需要隐藏的会话 ID 列表。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.hideInnerSessions(sessionIDList);

发起内部会话

调用此 API 可将发起客服之间的聊天。
接口
AIDeskCoreInstance.sessionService.startInnerSession(userId, nickName);
参数
参数
类型
默认值
描述
userId
string
-
用户 ID。
nickName
string
-
用户昵称。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

await AIDeskCoreInstance.sessionService.startInnerSession('userId', 'nickName');

查询历史会话记录

调用此 API 可查询当前客服的外部会话的记录列表。
接口
AIDeskCoreInstance.sessionService.getIMSessionRecords(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
pageNum
number
-
分页号。
pageSize
number
-
分页大小。
fromTime
number
-
起始时间戳，单位秒。
toTime
number
-
截止时间戳，单位秒。
staffUserId
string
-
当前客服的 ID。
返回值
Promise<object>
返回值为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
total
number
-
所有数据的条数。
data
object[]
-
会话记录列表。
data 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
sessionId
string
-
会话 ID。
timestamp
string
-
会话时间。
source
string
-
来源。
userId
string
-
用户 ID。
userNickName
string
-
用户昵称。
staffNickName
string
-
客服昵称。
staffUserId
string
-
客服 ID。
endStatus
string
-
服务状态。
skillGroupName
string
-
客服分组。
userBlacklist
object
-
用户拉黑数据。
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const res = await AIDeskCoreInstance.sessionService.getIMSessionRecords(options);

历史记录会话添加到本地会话列表

因为本地只存储两天内的结束状态的会话，如果需要查询两天前的会话需要模拟一个结束会话加入会话列表。
接口
AIDeskCoreInstance.sessionService.addRecordSession(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
sessionId
number
-
会话 ID。
userId
number
-
用户 ID。
avatar
number
-
用户头像。
nickname
string
-
用户昵称。
timestamp
string
-
会话时间戳。
clientData
string
-
会话自定义字段。
peerSource
string
-
会话来源。
channelAgentID
string
-
会话咨询入口。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.addRecordSession(options);

加入黑名单

调用此 API 可以将用户加入黑名单，可选择用户禁止转人工或使用机器人。
接口
AIDeskCoreInstance.sessionService.addBlacklist(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
userId
number
-
用户 ID。
beginTime
number
-
拉黑开始时间戳，单位秒。
endTime
number
-
拉黑结束时间戳，单位秒。
blockType
string
-
拉黑功能限制。
reason
string
-
拉黑原因。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.addBlacklist(options);

移出黑名单

调用此 API 可以将用户移出黑名单。
接口
AIDeskCoreInstance.sessionService.removeBlacklist(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
userId
number
-
用户 ID。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.removeBlacklist(options);

设置备注

调用此 API 可以将给会话的用户设置备注。
接口
AIDeskCoreInstance.sessionService.setUserRemark(options);
参数
参数 options 为 object 类型，包含的属性值如下：
参数
类型
默认值
描述
sessionId
number
-
会话 ID。
remark
number
-
备注信息。
返回值
无
示例
import AIDeskCoreInstance from '@tencentcloud/ai-desk-core';

const result = await AIDeskCoreInstance.sessionService.setUserRemark(options);
中国站