列出聊天
命名空间:microsoft.graph
检索用户所属 的聊天 列表。
此方法支持联合。 提供用户 ID 后,调用应用程序必须属于该用户所属的同一租户。
注意: 此 API 在一个或多个国家/地区云中的工作方式不同。 有关详细信息,请参阅 国家云中的实现差异。
此 API 可用于以下国家级云部署。
全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
要调用此 API,需要以下权限之一。 若要了解详细信息,包括如何选择权限的信息,请参阅权限。
权限类型 | 权限(从最低特权到最高特权) |
---|---|
委派(工作或学校帐户) | Chat.ReadBasic, Chat.Read, Chat.ReadWrite |
委派(个人 Microsoft 帐户) | 不支持。 |
应用程序 | Chat.ReadBasic.All*、Chat.Read.All*、Chat.ReadWrite.All* |
若要使用委派的权限在组织中获取已登录用户的聊天,请执行以下操作:
GET /chats
若要获取指定用户的聊天 (谁是组织中的已登录用户) 使用委派的权限:
GET /me/chats
GET /users/{user-id | user-principal-name}/chats
若要获取指定用户的聊天 (谁可能未登录或与组织中已登录的用户) 不同,请使用应用程序权限:
GET /users/{user-id | user-principal-name}/chats
此方法支持以下 OData 查询参数。
名称 | 说明 |
---|---|
$expand | 目前支持 成员 和 lastMessagePreview 属性。 |
$top | 控制每个响应的项数。 允许的最大 $top 值为 50。 |
$filter | 筛选结果。 |
$orderby | 目前支持按降序排列 的 lastMessagePreview/createdDateTime 。 目前不支持升序顺序。 |
目前不支持其他 OData 查询参数。
备注
查询 $top
参数可能不会返回单个响应对象中的所有聊天。 如果所有聊天的结果集跨越多个页面,则响应对象将包含包含指向下一页结果的 URL 的 @odata.nextLink 属性。 如果该属性存在,请继续在每个响应中使用 @odata.nextLink URL 发出其他请求,直到返回所有结果。
标头 | 值 |
---|---|
Authorization | 持有者 {token}。 必填。 详细了解 身份验证和授权。 |
请勿提供此方法的请求正文。
如果成功,此方法在响应正文中返回 200 OK
响应代码和 chat 对象集合。
以下示例显示了一个请求。
GET https://graph.microsoft.com/v1.0/users/8b081ef6-4792-4def-b2c9-c363a1bf41d5/chats
以下示例显示了相应的响应。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats",
"@odata.count": 3,
"value": [
{
"id": "19:meeting_MjdhNjM4YzUtYzExZi00OTFkLTkzZTAtNTVlNmZmMDhkNGU2@thread.v2",
"topic": "Meeting chat sample",
"createdDateTime": "2020-12-08T23:53:05.801Z",
"lastUpdatedDateTime": "2020-12-08T23:58:32.511Z",
"chatType": "meeting",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-06-03T08:05:49.521Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3Ameeting_MjdhNjM4YzUtYzExZi00OTFkLTkzZTAtNTVlNmZmMDhkNGU2@thread.v2/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f"
},
{
"id": "19:561082c0f3f847a58069deb8eb300807@thread.v2",
"topic": "Group chat sample",
"createdDateTime": "2020-12-03T19:41:07.054Z",
"lastUpdatedDateTime": "2020-12-08T23:53:11.012Z",
"chatType": "group",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-05-27T22:13:01.577Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3A561082c0f3f847a58069deb8eb300807@thread.v2/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f"
},
{
"id": "19:d74fc2ed-cb0e-4288-a219-b5c71abaf2aa_8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2020-12-04T23:10:28.51Z",
"lastUpdatedDateTime": "2020-12-04T23:10:36.925Z",
"chatType": "oneOnOne",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "0001-01-01T00:00:00Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3Ad74fc2ed-cb0e-4288-a219-b5c71abaf2aa_8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca@unq.gbl.spaces/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f"
}
]
}
以下示例显示了一个请求。
GET https://graph.microsoft.com/v1.0/users/8b081ef6-4792-4def-b2c9-c363a1bf41d5/chats?$expand=members
以下示例显示了相应的响应。
备注
服务器返回的成员 ID 必须作为不透明的字符串处理。 客户端不应尝试分析这些资源 ID 或做出任何假设。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats(members())",
"@odata.count": 3,
"value": [
{
"id": "19:meeting_MjdhNjM4YzUtYzExZi00OTFkLTkzZTAtNTVlNmZmMDhkNGU2@thread.v2",
"topic": "Meeting chat sample",
"createdDateTime": "2020-12-08T23:53:05.801Z",
"lastUpdatedDateTime": "2020-12-08T23:58:32.511Z",
"chatType": "meeting",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-04-02T08:15:02.091Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3Ameeting_MjdhNjM4YzUtYzExZi00OTFkLTkzZTAtNTVlNmZmMDhkNGU2@thread.v2/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f",
"members": [
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "Tony Stark",
"userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
"email": "starkt@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMz6Jk45=",
"roles": [],
"displayName": "Peter Parker",
"userId": "d74fc2ed-cb0e-4288-a219-b5c71abaf2aa",
"email": "parkerp@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJ989kMTQ=",
"roles": [],
"displayName": "Nick Fury",
"userId": "8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca",
"email": "furyn@contoso.com"
}
]
},
{
"id": "19:561082c0f3f847a58069deb8eb300807@thread.v2",
"topic": "Group chat sample",
"createdDateTime": "2020-12-03T19:41:07.054Z",
"lastUpdatedDateTime": "2020-12-08T23:53:11.012Z",
"chatType": "group",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "0001-01-01T00:00:00Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3A561082c0f3f847a58069deb8eb300807@thread.v2/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f",
"members": [
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "Tony Stark",
"userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
"email": "starkt@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM312ftMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "Bruce Banner",
"userId": "48bf9d52-dca7-4a5f-8398-37b95cc7bd83",
"email": "bannerb@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWai3MTetN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "TChalla",
"userId": "9efb1aea-4f83-4673-bdcd-d3f3c7be28c2",
"email": "tchalla@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwamii00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "Thor Odinson",
"userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
"email": "odinsont@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWopiLWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJkM123=",
"roles": [],
"displayName": "Steve Rogers",
"userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
"email": "rogerss@contoso.com"
}
]
},
{
"id": "19:d74fc2ed-cb0e-4288-a219-b5c71abaf2aa_8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2020-12-04T23:10:28.51Z",
"lastUpdatedDateTime": "2020-12-04T23:10:36.925Z",
"chatType": "oneOnOne",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-06-05T00:31:30.047Z"
},
"webUrl": "https://teams.microsoft.com/l/chat/19%3Ad74fc2ed-cb0e-4288-a219-b5c71abaf2aa_8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca@unq.gbl.spaces/0?tenantId=b33cbe9f-8ebe-4f2a-912b-7e2a427f477f",
"members": [
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMzJ989kMTQ=",
"roles": [],
"displayName": "Nick Fury",
"userId": "8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca",
"email": "furyn@contoso.com"
},
{
"@odata.type": "#microsoft.graph.aadUserConversationMember",
"id": "MmFiOWM3OTYtMjkwMi00NWY4LWI3MTItN2M1YTYzY2Y0MWM0IyNlZWY5Y2IzNi0wNmRlLTQ2OWItODdjZC03MGY0Y2JlMz6Jk45=",
"roles": [],
"displayName": "Peter Parker",
"userId": "d74fc2ed-cb0e-4288-a219-b5c71abaf2aa",
"email": "parkerp@contoso.com"
}
]
}
]
}
以下示例显示了一个请求。 lastMessagePreview/createdDateTime 传递给按最晚到最不最近的聊天消息对聊天进行排序。
GET https://graph.microsoft.com/v1.0/chats?$orderby=lastMessagePreview/createdDateTime desc
以下示例显示了相应的响应。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats",
"@odata.count": 2,
"@odata.nextLink": "https://graph.microsoft.com/v1.0/chats?$orderby=lastMessagePreview%2fcreatedDateTime+desc&$skiptoken=1.kscDYs0BbsYAAAFa8ZyBqlByb3BlcnRpZXOCqVN5bmNTdGF0ZdoBRGV5SmtaV3hwZG1WeVpXUlRaV2R0Wlc1MGN5STZXM3NpYzNSaGNuUWlPaUl5TURJeExUQTRMVEUzVkRFeE9qVXpPakUxTGprd09Tc3dNRG93TUNJc0ltVnVaQ0k2SWpJd01qSXRNRFV0TUROVU1UZzZNVFU2TkRJdU16QTNLekF3T2pBd0luMHNleUp6ZEdGeWQ4APMDRTVOekF0TURFdE1ERlVNREE2BAATcggAcWlMQ0psYm2YAJB4T1Rjd0xUQXgEACJWRFQAAAQABmAA8F8xZExDSjZaWEp2VEUxVFZFUmxiR2wyWlhKbFpGTmxaMjFsYm5SeklqcGJYU3dpYzI5eWRFOXlaR1Z5SWpveExDSnBibU5zZFdSbFdtVnliMHhOVTFRaU9uUnlkV1Y5rExhc3RQYWdlU2l6ZaIyMA%3d%3d",
"value": [
{
"id": "19:670374fa-3b0e-4a3b-9d33-0e1bc5ff1956_bfb5bb25-3a8d-487d-9828-7875ced51a30@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2021-11-17T18:48:57.986Z",
"lastUpdatedDateTime": "2021-11-17T18:48:57.986Z",
"chatType": "oneOnOne",
"webUrl": "https://teams.microsoft.com/l/chat/19%3A670374fa-3b0e-4a3b-9d33-0e1bc5ff1956_bfb5bb25-3a8d-487d-9828-7875ced51a30%40unq.gbl.spaces/0?tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34",
"tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
"onlineMeetingInfo": null,
"viewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2022-05-03T18:15:42.307Z"
}
},
{
"id": "19:82fe7758-5bb3-4f0d-a43f-e555fd399c6f_bfb5bb25-3a8d-487d-9828-7875ced51a30@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2021-05-26T00:07:00.751Z",
"lastUpdatedDateTime": "2021-05-26T00:07:14.894Z",
"chatType": "oneOnOne",
"webUrl": "https://teams.microsoft.com/l/chat/19%3A82fe7758-5bb3-4f0d-a43f-e555fd399c6f_bfb5bb25-3a8d-487d-9828-7875ced51a30%40unq.gbl.spaces/0?tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34",
"tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
"onlineMeetingInfo": null,
"viewpoint": {
"isHidden": true,
"lastMessageReadDateTime": "2022-03-08T19:55:30.491Z"
}
}
]
}
以下示例显示了列出聊天的请求,以及聊天中最后发送的消息的预览。 将 createdDateTime
预览版与 lastMessageReadDateTime
中 viewpoint
进行比较可让调用方确定用户是否已阅读聊天中的所有消息。
GET https://graph.microsoft.com/v1.0/chats?$expand=lastMessagePreview
以下示例显示了相应的响应。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats(lastMessagePreview())",
"@odata.count": 3,
"@odata.nextLink": "https://graph.microsoft.com/v1.0/chats?$expand=lastMessagePreview&$skiptoken=eyJDb250aW51YXRpb25Ub2tlbiI6Ilczc2ljM1JoY25RaU9pSXlNREl4TFRBMUxUSTNWREl5T2pFek9qQXpMakUyT1Nzd01Eb3dNQ0lzSW1WdVpDSTZJakl3TWpFdE1EWXRNRFZVTURBNk16RTZNekl1T0RBMkt6QXdPakF3SW4wc2V5SnpkR0Z5ZENJNklqRTVOekF0TURFdE1ERlVNREE2TURBNk1EQXJNREE2TURBaUxDSmxibVFpT2lJeE9UY3dMVEF4TFRBeFZEQXdPakF3T2pBd0xqQXdNU3N3TURvd01DSjlYUT09IiwiQ2hhdFR5cGUiOiJjaGF0fG1lZXRpbmd8c2ZiaW50ZXJvcGNoYXR8cGhvbmVjaGF0In0%3d",
"value": [
{
"id": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2021-06-05T00:31:30.767Z",
"lastUpdatedDateTime": "2021-06-05T00:31:32.806Z",
"chatType": "oneOnOne",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-06-05T00:31:30.047Z"
},
"lastMessagePreview": {
"id": "1622853091207",
"createdDateTime": "2021-06-05T00:31:31.207Z",
"isDeleted": false,
"messageType": "message",
"eventDetail": null,
"body": {
"contentType": "text",
"content": "Testing unread read status"
},
"from": {
"application": null,
"device": null,
"user": {
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Nick Fury",
"userIdentityType": "aadUser"
}
}
}
},
{
"id": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_da7d471b-de7d-4152-8556-1cdf7a564f6c@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2020-07-17T22:46:28.077Z",
"lastUpdatedDateTime": "2021-06-03T08:05:49.788Z",
"chatType": "oneOnOne",
"chatViewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-06-03T08:05:49.521Z"
},
"lastMessagePreview": {
"id": "1622707540293",
"createdDateTime": "2021-06-03T08:05:40.293Z",
"isDeleted": false,
"messageType": "message",
"eventDetail": null,
"body": {
"contentType": "html",
"content": "<attachment id=\"ee8d34acd36d4dfe87ca6ad4e060b7be\"></attachment>"
},
"from": {
"device": null,
"user": null,
"application": {
"id": "da7d471b-de7d-4152-8556-1cdf7a564f6c",
"displayName": "talla",
"applicationIdentityType": "bot"
}
}
}
},
{
"id": "19:7b5c1643d8d74a03afa0af9c02dd0ef2@thread.v2",
"topic": "Group chat",
"createdDateTime": "2021-07-18T22:12:17.231Z",
"lastUpdatedDateTime": "2021-06-04T05:34:23.980Z",
"chatType": "group",
"webUrl": "https://teams.microsoft.com/l/chat/19%3A7b5c1643d8d74a03afa0af9c02dd0ef2%40thread.v2/0?tenantId=df81db53-c7e2-418a-8803-0e68d4b88607",
"viewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2021-06-04T05:34:23.712Z"
},
"lastMessagePreview": {
"id": "1622784857324",
"createdDateTime": "2021-06-04T05:34:17.324Z",
"isDeleted": false,
"messageType": "systemEventMessage",
"from": null,
"body": {
"contentType": "html",
"content": "<systemEventMessage/>"
},
"eventDetail": {
"@odata.type": "#microsoft.graph.membersAddedEventMessageDetail",
"visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
"members": [
{
"id": "d9a2f9a8-6ca9-4c92-9a1c-ceca33b91762",
"displayName": null,
"userIdentityType": "aadUser"
}
],
"initiator": {
"application": null,
"device": null,
"user": {
"id": "1fb8890f-423e-4154-8fbf-db6809bc8756",
"displayName": null,
"userIdentityType": "aadUser"
}
}
}
}
}
]
}
以下示例显示了一个请求。
GET https://graph.microsoft.com/v1.0/users/e652dd92-dd63-4fcc-b5b2-2005681e8e9f/chats?$filter=installedApps/any(a:a/teamsApp/id eq '608d8644-acb1-4ab0-bca5-66fbb6ed62aa')
以下示例显示了相应的响应。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats",
"@odata.count": 1,
"value": [
{
"id": "19:e652dd92-dd63-4fcc-b5b2-2005681e8e9f_734601fc-bbcd-4a30-9092-3c89f8d788cb@unq.gbl.spaces",
"topic": null,
"createdDateTime": "2023-03-03T11:32:33.631Z",
"lastUpdatedDateTime": "2023-06-08T06:02:19.072Z",
"chatType": "oneOnOne",
"webUrl": "https://teams.microsoft.com/l/chat/19%3Ae652dd92-dd63-4fcc-b5b2-2005681e8e9f_734601fc-bbcd-4a30-9092-3c89f8d788cb%40unq.gbl.spaces/0?tenantId=aa923623-ae61-49ee-b401-81f414b6ad5a",
"tenantId": "aa923623-ae61-49ee-b401-81f414b6ad5a",
"onlineMeetingInfo": null,
"viewpoint": {
"isHidden": false,
"lastMessageReadDateTime": "2023-06-29T10:22:15.024Z"
}
}
]
}