会话摘要 RESTful API

大约 9 分钟

会话摘要 RESTful API

你可以使用 RESTful API 生成、获取和删除群组会话一段时间内的聊天内容的摘要。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

公共请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息
group_idString群组 ID。

认证方式

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式,详见 使用 App Token 鉴权

生成会话摘要

你可以为群聊会话中指定时间范围内的消息生成摘要,列明该摘要涉及的各个话题的详细信息。

调用频率上限:100 次/秒/App Key

HTTP 请求

POST https://{host}/{org_name}/{app_name}/agent/v1/messages/summary
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。填入 application/json
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必须描述
conversationIdString群组 ID。目前,即时通讯 IM 仅支持群组的会话内容摘要。
usernameString会话摘要生成者的用户 ID。
- 若传入了指定的用户 ID,则该会话摘要由该用户生成,属于该用户私有的摘要。对于单个群组会话,最多可为单个用户生成 20 个会话摘要。
- 若不传入任何用户 ID,则该会话摘要没有特定生成者,属于群组的公开摘要。对于单个群组会话,最多可生成 20 个群聊的公开摘要。
chatTypeString聊天类型,chatgroup 为群组类型。
startTimestampLong生成会话内容摘要的起始时间,UNIX 时间戳,单位为毫秒。
endTimestampLong生成会话内容摘要的结束时间,UNIX 时间戳,单位为毫秒。你最多可生成 48 小时内聊天内容的摘要。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
codeString请求是否成功。200 表示请求成功。
dataJSON请求结果。
data.summaryIdString会话摘要 ID。
data.topicInfosJSONArray会话摘要中的话题信息。
data.topicInfos.titleString话题的标题。
data.topicInfos.contentString话题的内容。
data.topicInfos.participantsArray话题中参与者的用户 ID。
data.topicInfos.msgCountInt该话题涉及的消息数量。
data.topicInfos.firstMsgIdLong该话题涉及的首条消息的时间戳。
data.topicInfos.lastMsgIdLong该话题涉及的最后一条消息的时间戳。
data.generatorString会话摘要的生成者。如果为 null,表示该会话摘要是利用 app token 调用 RESTful API 生成且没有指定生成者(未传入查询参数 username)。
data.summaryTimestampLong会话摘要生成的时间戳。
data.imageUrlsArray会话摘要涉及的图片的 URL。
data.videoUrlsArray会话摘要涉及的视频的 URL。
data.messageContentListArray会话摘要涉及的消息内容列表。

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考错误码了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST http://XXXX/XXXX/XXXX/agent/v1/messages/summary  \
-H 'Authorization: Bearer <YourAppToken>'  \
-H 'Content-Type: application/json'  \
-H 'Accept: application/json'  \
-d '{
    "conversationId" : "260052191608833",
    "username" : "u3",
    "chatType" : "chatgroup",
    "startTimestamp" : 1727403468000,
    "endTimestamp" : 1727403679000
}'
响应示例
{
    "code": 200,
    "data": {
        "summaryId": "e23689e29647415b9799f2d9b11c3861",
        "topicInfos": [
            {
                "title": "午饭吃什么的讨论",
                "content": "讨论关于今天午饭的选择,包括饺子和其他可能的食物。",
                "participants": [
                    "u5"
                ],
                "msgCount": "3",
                "firstMsgId": "1330747175658850260",
                "lastMsgId": "1330747200933726164"
            }
        ],
        "generator" : "u3", 
        "summaryTimestamp": 1727423674695,
        "imageUrls": [],
        "videoUrls": [],
        "messageContentList" : [] 
    }
}

错误码

如果返回的 HTTP 状态码非 200,表示请求失败,可能提示以下错误码:

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。

关于其他错误,你可以参考响应状态码了解可能的原因。

获取会话摘要

你可以获取指定群聊会话的摘要信息,查看摘要中各话题的信息。

调用频率上限:100 次/秒/App Key

HTTP 请求

GET https://{host}/{org_name}/{app_name}/agent/v1/messages/summaries?conversationId={groupId}&username={username}&chatType={chatType}
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
查询参数
参数类型是否必须描述
conversationIdString群组 ID。目前,即时通讯 IM 仅支持群组的会话内容摘要。
usernameString会话摘要的生成者。
- 若传入指定的用户 ID,即时通讯 IM 仅获取该用户生成的所有私有会话摘要。
- 若不传入任何用户 ID,则获取该该群组会话的所有公开摘要,即调用 RESTful API 生成会话摘要时,未传入指定用户 ID(username)而生成的摘要。
chatTypeString聊天类型,chatgroup 为群组类型。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
codeString请求是否成功。200 表示请求成功。
dataJSON请求结果。
data.summaryIdString会话摘要 ID。
data.topicInfosJSONArray会话摘要中的话题信息。
data.topicInfos.titleString话题的标题。
data.topicInfos.contentString话题的内容。
data.topicInfos.participantsArray该话题的参与者的用户 ID。
data.topicInfos.msgCountInt该话题涉及的消息数量。
data.topicInfos.firstMsgIdLong该话题涉及的首条消息的时间戳。
data.topicInfos.lastMsgIdLong该话题涉及的最后一条消息的时间戳。
data.generatorString会话摘要的生成者。如果为 null,表示该会话摘要是群组的公开摘要,即该摘要是利用 app token 调用 RESTful API 生成且未指定生成者(未传入查询参数 username)。
data.summaryTimestampLong会话摘要生成的时间戳。
data.imageUrlsArray会话摘要涉及的图片的 URL。
data.videoUrlsArray会话摘要涉及的视频的 URL。
data.messageContentListArray会话摘要涉及的消息内容列表。

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考错误码了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET 'http://XXXX/XXXX/XXXX/agent/v1/messages/summaries?conversationId=260052191608833&username=u3&chatType=chatgroup' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>'
响应示例
{
    "code": 200,
    "data": [
        {
            "summaryId": "e23689e29647415b9799f2d9b11c3861",
            "topicInfos": [
                {
                    "title": "午饭吃什么的讨论",
                    "content": "讨论关于今天午饭的选择,包括饺子和其他可能的食物。",
                    "participants": [
                        "u5"
                    ],
                    "msgCount": "3",
                    "firstMsgId": "1330747175658850260",
                    "lastMsgId": "1330747200933726164"
                }
            ],
            "generator" : "u5", // 新增参数摘要的生成者,如果为null说明是调用rest api使用app token生成的
            "summaryTimestamp": 1727423674695,
            "imageUrls": [],
            "videoUrls": [],
            "messageContentList" : [] // 新增参数消息内容列表
        },
        {
            "summaryId": "dbbb3e40c3694e428d5251a40cd74107",
            "topicInfos": [
                {
                    "title": "午餐吃什么的讨论",
                    "content": "讨论关于午餐的选择,包括饺子和其他可能的食物。",
                    "participants": [
                        "u5"
                    ],
                    "msgCount": "3",
                    "firstMsgId": "1330747175658850260",
                    "lastMsgId": "1330747200933726164"
                }
            ],
            "generator" : "u5", // 新增参数摘要的生成者,如果为null说明是调用rest api使用app token生成的
            "summaryTimestamp": 1727422710699,
            "imageUrls": [],
            "videoUrls": [],
            "messageContentList" : [] 
        }
    ]
}

错误码

如果返回的 HTTP 状态码非 200,表示请求失败,可能提示以下错误码:

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。

关于其他错误,你可以参考响应状态码了解可能的原因。

删除会话摘要

你可以删除群组会话中指定的会话摘要。

调用频率上限:100 次/秒/App Key

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/agent/v1/messages/summary/{summaryId}?conversationId={groupId}&username={username}&chatType={chatType}
路径参数
参数类型是否必需描述
summaryIdString要删除的会话摘要 ID。

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
查询参数
参数类型是否必须描述
conversationIdString群组 ID。目前,即时通讯 IM 仅支持群组会话的内容摘要。
usernameString会话摘要生成者的用户 ID。
- 若传入了指定的用户 ID,即时通讯 IM 删除该用户生成的特定的私有会话摘要。
- 若不传入任何用户 ID,则删除群组指定的公开摘要,即生成时未指定用户 ID (username) 的摘要。
chatTypeString聊天类型,chatgroup 为群组类型。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
codeString请求是否成功。200 表示请求成功。

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考错误码了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE 'http://XXXX/XXXX/XXXX/agent/v1/messages/summary/38c30ced8cc24fbd86b6ba79d4f57397?conversationId=260052191608833&username=u3&chatType=chatgroup' \
-H 'Accept: application/json'   \
-H 'Authorization: Bearer <YourAppToken>'
响应示例
{
    "code": 200
}

错误码

如果返回的 HTTP 状态码非 200,表示请求失败,可能提示以下错误码:

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。

关于其他错误,你可以参考响应状态码了解可能的原因。