📖 Microsoft Teams API 使用指南

Microsoft Graph API - Chat Integration

← 返回Teams管理 🏠 回到导航页面

📑 快速导航

1 🔑 认证与授权
Microsoft Graph API 认证流程

使用OAuth 2.0进行身份验证，需要获取Access Token才能调用API。

所需权限（Scopes）：

⚠️ 重要提示 Access Token有效期为1小时，过期后需要使用Refresh Token刷新。系统已集成自动刷新功能。
2 👥 获取聊天列表
接口地址：GET https://graph.microsoft.com/v1.0/me/chats

Curl 示例：

curl --location 'https://graph.microsoft.com/v1.0/me/chats?$top=50' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
--header 'Accept: application/json'

查询参数：

参数 类型 说明
$top int 返回的聊天数量（默认50，最大50）

响应示例：

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats",
  "@odata.count": 9,
  "value": [
    {
      "id": "19:dL5W5f8U1ZDYLzMFpEKrp7PQ8Wr5JIcibVxdGwzdDOc1@thread.v2",
      "topic": "PSA Amazon x BF Operation",
      "createdDateTime": "2025-06-02T01:46:55.171Z",
      "lastUpdatedDateTime": "2025-11-06T07:37:31.968Z",
      "chatType": "group",
      "tenantId": "9188040d-6c67-4c5b-b112-36a304b66dad"
    }
  ]
}
3 👤 获取群组成员
接口地址：GET https://graph.microsoft.com/v1.0/chats/{chat-id}/members

Curl 示例：

curl --location 'https://graph.microsoft.com/v1.0/chats/19:CHAT_ID@thread.v2/members' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
--header 'Accept: application/json'

路径参数：

参数 类型 说明
chat-id string 聊天的唯一标识符

响应示例：

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#members",
  "value": [
    {
      "displayName": "John Smith",
      "email": "john@example.com",
      "userId": "29133-e297-416e-ace0-67c679949f0d",
      "roles": ["owner"],
      "visibleHistoryStartDateTime": "2025-06-02T01:46:55.171Z"
    }
  ]
}
4 💬 获取聊天消息
接口地址：GET https://graph.microsoft.com/v1.0/chats/{chat-id}/messages

Curl 示例：

curl --location 'https://graph.microsoft.com/v1.0/chats/19:CHAT_ID@thread.v2/messages?$top=50&$orderby=createdDateTime desc' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
--header 'Accept: application/json'

查询参数：

参数 类型 说明
$top int 返回的消息数量（1-50）
$orderby string 排序方式，仅支持：createdDateTime desc
$skiptoken string 分页token（从@odata.nextLink获取）
⚠️ API限制
  • 不支持 $filter 参数（时间过滤需在客户端完成）
  • 不支持升序排序（仅支持降序）
  • 使用 @odata.nextLink 进行分页

响应示例：

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#chats('...')/messages",
  "@odata.count": 10,
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/chats/.../messages?$top=10&$skiptoken=...",
  "value": [
    {
      "id": "1762409226255",
      "messageType": "message",
      "createdDateTime": "2025-11-06T06:07:06.255Z",
      "from": {
        "user": {
          "id": "efe3e583c156b2d6",
          "displayName": "BESTFULFILL- Aurora"
        }
      },
      "body": {
        "contentType": "html",
        "content": "
Ok we will source for you
"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}
5 🔄 刷新Access Token
接口地址：POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token

Curl 示例：

curl --location 'https://login.microsoftonline.com/23dce5d2-92cc-4efa-be2e-6e0ec7306649/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=3310a722-f802-4986-9422-43a17795f77d' \
--data-urlencode 'refresh_token={YOUR_REFRESH_TOKEN}'

请求参数：

参数 类型 说明
grant_type string 固定值：refresh_token
client_id string 应用程序ID
refresh_token string 刷新令牌

响应示例：

{
  "token_type": "Bearer",
  "scope": "Chat.Read Chat.ReadBasic ChatMember.Read...",
  "expires_in": 4810,
  "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
  "refresh_token": "1.AcYA0uXcI8yS-k6-Lm4OxzBm..."
}
✅ 自动刷新 系统已集成自动刷新功能，当检测到Access Token过期时，会自动提示刷新，并保存新的token。
6 ❓ 常见问题

Q: 为什么查询消息不能按时间过滤？

A: Microsoft Teams的 /messages 端点不支持 $filter 参数。系统会获取所有消息后在客户端按时间范围过滤。

Q: 为什么只能降序排列？

A: Teams API仅支持 $orderby=createdDateTime desc，不支持升序排序。

Q: Access Token多久过期？

A: 通常1小时后过期，过期时系统会提示使用Refresh Token刷新。

Q: 如何获取初始的Access Token？

A: 需要在Azure Portal创建应用程序并配置权限，然后通过OAuth 2.0授权流程获取。

7 🔗 相关链接