Skip to content

Commit 5984069

Browse files
FaithOmbongiFaithOmbongi
authored
Merge pull request #28128 from microsoftgraph/planner/pavlodatsiuk/taskchat-api
Add documentation for Planner task chat messaging API (beta)
2 parents 5e1b68d + 5722c89 commit 5984069

23 files changed

Lines changed: 1186 additions & 2 deletions

‎api-reference/beta/api/plannertask-list-messages.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: "List messages"
3+
description: "Retrieve a list of plannerTaskChatMessage objects associated with a plannerTask."
4+
author: "pavlodatsiuk"
5+
ms.localizationpriority: medium
6+
ms.subservice: "planner"
7+
doc_type: apiPageType
8+
ms.date: 01/23/2026
9+
---
10+
11+
# List messages
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Retrieve a list of [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) objects associated with a [plannerTask](../resources/plannertask.md).
18+
19+
[!INCLUDE [national-cloud-support](../../includes/global-us.md)]
20+
21+
## Permissions
22+
23+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "plannertask_list_messages" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/plannertask-list-messages-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
GET /planner/tasks/{task-id}/messages
33+
```
34+
35+
## Optional query parameters
36+
37+
This method supports the `$skipToken` query parameter for paging. This method doesn't support other OData query parameters.
38+
39+
## Request headers
40+
41+
| Name |Description|
42+
|:----------|:----------|
43+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
44+
45+
## Request body
46+
47+
Don't supply a request body for this method.
48+
49+
## Response
50+
51+
If successful, this method returns a `200 OK` response code and a collection of [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) objects in the response body.
52+
53+
This method can return any of the [HTTP status codes](/graph/errors). The most common errors that apps should handle for this method are the 403 and 404 responses. For more information about these errors, see [Common Planner error conditions](../resources/planner-overview.md#common-planner-error-conditions).
54+
55+
## Example
56+
57+
### Request
58+
59+
The following example shows a request.
60+
61+
<!-- {
62+
"blockType": "request",
63+
"name": "plannertask_list_messages",
64+
"sampleKeys": ["01gzSlKkIUSUl6DF_EilrmQAKDhh"]
65+
}-->
66+
```http
67+
GET https://graph.microsoft.com/beta/planner/tasks/01gzSlKkIUSUl6DF_EilrmQAKDhh/messages
68+
```
69+
70+
### Response
71+
72+
The following example shows the response.
73+
74+
>**Note:** The response object shown here might be shortened for readability.
75+
76+
<!-- {
77+
"blockType": "response",
78+
"truncated": true,
79+
"@odata.type": "microsoft.graph.plannerTaskChatMessage",
80+
"isCollection": true
81+
} -->
82+
```http
83+
HTTP/1.1 200 OK
84+
Content-type: application/json
85+
86+
{
87+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#planner/tasks('01gzSlKkIUSUl6DF_EilrmQAKDhh')/messages",
88+
"@odata.count": 1,
89+
"value": [
90+
{
91+
"id": "5bde7bc8-d998-4e8a-8159-93d4d7ccc3b5",
92+
"messageType": "richTextHtml",
93+
"content": "This is the message content",
94+
"createdDateTime": "2025-11-29T00:39:31.319Z",
95+
"parentEntityId": "01gzSlKkIUSUl6DF_EilrmQAKDhh",
96+
"deletedTime": null,
97+
"editedTime": null,
98+
"mentions": [],
99+
"reactions": [],
100+
"createdBy": {
101+
"user": {
102+
"id": "6463a5ce-2119-4198-9f2a-628761df4a62"
103+
}
104+
}
105+
}
106+
]
107+
}
108+
```
109+
110+
<!-- {
111+
"type": "#page.annotation",
112+
"description": "List plannerTaskChatMessage",
113+
"keywords": "",
114+
"section": "documentation",
115+
"tocPath": ""
116+
}-->

‎api-reference/beta/api/plannertask-post-messages.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: "Create plannerTaskChatMessage"
3+
description: "Create a new chat message on a planner task."
4+
author: "pavlodatsiuk"
5+
ms.localizationpriority: medium
6+
ms.subservice: "planner"
7+
doc_type: apiPageType
8+
ms.date: 01/23/2026
9+
---
10+
11+
# Create plannerTaskChatMessage
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Create a new [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) on a [plannerTask](../resources/plannertask.md).
18+
19+
[!INCLUDE [national-cloud-support](../../includes/global-us.md)]
20+
21+
## Permissions
22+
23+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "plannertask_post_messages" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/plannertask-post-messages-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
POST /planner/tasks/{task-id}/messages
33+
```
34+
35+
## Request headers
36+
37+
| Name | Description|
38+
|:-----------|:-----------|
39+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
40+
| Content-Type | application/json. Required.|
41+
42+
## Request body
43+
44+
In the request body, supply a JSON representation of a [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) object.
45+
46+
The following table lists the properties that you can set when you create a **plannerTaskChatMessage**.
47+
48+
| Property | Type |Description|
49+
|:---------------|:--------|:----------|
50+
| content | String | The content of the chat message. This property supports plain text and sanitized HTML. Required. |
51+
| mentions | [plannerTaskChatMention](../resources/plannertaskchatmention.md) collection | The list of mentions in the message. Optional. |
52+
53+
## Response
54+
55+
If successful, this method returns a `201 Created` response code and a [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) object in the response body.
56+
57+
This method can return any of the [HTTP status codes](/graph/errors). The most common errors that apps should handle for this method are the 400, 403, and 404 responses. For more information about these errors, see [Common Planner error conditions](../resources/planner-overview.md#common-planner-error-conditions).
58+
59+
## Examples
60+
61+
### Example 1: Create a message
62+
63+
#### Request
64+
65+
The following example shows a request to create a chat message.
66+
67+
<!-- {
68+
"blockType": "request",
69+
"name": "plannertask_post_messages",
70+
"sampleKeys": ["01gzSlKkIUSUl6DF_EilrmQAKDhh"]
71+
}-->
72+
```http
73+
POST https://graph.microsoft.com/beta/planner/tasks/01gzSlKkIUSUl6DF_EilrmQAKDhh/messages
74+
Content-type: application/json
75+
76+
{
77+
"content": "This is a new chat message"
78+
}
79+
```
80+
81+
#### Response
82+
83+
The following example shows the response.
84+
85+
<!-- {
86+
"blockType": "response",
87+
"truncated": true,
88+
"@odata.type": "microsoft.graph.plannerTaskChatMessage"
89+
} -->
90+
```http
91+
HTTP/1.1 201 Created
92+
Content-type: application/json
93+
94+
{
95+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#planner/tasks('01gzSlKkIUSUl6DF_EilrmQAKDhh')/messages/$entity",
96+
"id": "5bde7bc8-d998-4e8a-8159-93d4d7ccc3b5",
97+
"messageType": "richTextHtml",
98+
"content": "This is a new chat message",
99+
"createdDateTime": "2025-12-05T17:49:39.593Z",
100+
"parentEntityId": "01gzSlKkIUSUl6DF_EilrmQAKDhh",
101+
"deletedTime": null,
102+
"editedTime": null,
103+
"mentions": [],
104+
"reactions": [],
105+
"createdBy": {
106+
"user": {
107+
"id": "6463a5ce-2119-4198-9f2a-628761df4a62"
108+
}
109+
}
110+
}
111+
```
112+
113+
### Example 2: Create a message with mentions
114+
115+
#### Request
116+
117+
The following example shows a request to create a chat message with a user mention.
118+
119+
<!-- {
120+
"blockType": "request",
121+
"name": "plannertask_post_messages_with_mentions",
122+
"sampleKeys": ["01gzSlKkIUSUl6DF_EilrmQAKDhh"]
123+
}-->
124+
```http
125+
POST https://graph.microsoft.com/beta/planner/tasks/01gzSlKkIUSUl6DF_EilrmQAKDhh/messages
126+
Content-type: application/json
127+
128+
{
129+
"content": "<div><span itemid=\"0\" itemtype=\"https://schema.skype.com/Mention/Person\"></span> Please review this task</div>",
130+
"mentions": [
131+
{
132+
"mentioned": "6463a5ce-2119-4198-9f2a-628761df4a62",
133+
"position": 0,
134+
"mentionType": "user"
135+
}
136+
]
137+
}
138+
```
139+
140+
#### Response
141+
142+
The following example shows the response.
143+
144+
<!-- {
145+
"blockType": "response",
146+
"truncated": true,
147+
"@odata.type": "microsoft.graph.plannerTaskChatMessage"
148+
} -->
149+
```http
150+
HTTP/1.1 201 Created
151+
Content-type: application/json
152+
153+
{
154+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#planner/tasks('01gzSlKkIUSUl6DF_EilrmQAKDhh')/messages/$entity",
155+
"id": "7cde8bc9-e109-5f9b-9260-04e5e8ddc4c6",
156+
"messageType": "richTextHtml",
157+
"content": "<div><span itemid=\"0\" itemtype=\"https://schema.skype.com/Mention/Person\"></span> Please review this task</div>",
158+
"createdDateTime": "2025-12-05T17:49:39.593Z",
159+
"parentEntityId": "01gzSlKkIUSUl6DF_EilrmQAKDhh",
160+
"deletedTime": null,
161+
"editedTime": null,
162+
"mentions": [
163+
{
164+
"mentioned": "6463a5ce-2119-4198-9f2a-628761df4a62",
165+
"position": 0,
166+
"mentionType": "user"
167+
}
168+
],
169+
"reactions": [],
170+
"createdBy": {
171+
"user": {
172+
"id": "6463a5ce-2119-4198-9f2a-628761df4a62"
173+
}
174+
}
175+
}
176+
```
177+
178+
<!-- {
179+
"type": "#page.annotation",
180+
"description": "Create plannerTaskChatMessage",
181+
"keywords": "",
182+
"section": "documentation",
183+
"tocPath": ""
184+
}-->

‎api-reference/beta/api/plannertaskchatmessage-delete.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: "Delete plannerTaskChatMessage"
3+
description: "Delete a plannerTaskChatMessage object."
4+
author: "pavlodatsiuk"
5+
ms.localizationpriority: medium
6+
ms.subservice: "planner"
7+
doc_type: apiPageType
8+
ms.date: 01/23/2026
9+
---
10+
11+
# Delete plannerTaskChatMessage
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Delete a [plannerTaskChatMessage](../resources/plannertaskchatmessage.md) object.
18+
19+
[!INCLUDE [national-cloud-support](../../includes/global-us.md)]
20+
21+
## Permissions
22+
23+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "plannertaskchatmessage_delete" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/plannertaskchatmessage-delete-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
DELETE /planner/tasks/{task-id}/messages/{message-id}
33+
```
34+
35+
## Request headers
36+
37+
| Name | Description|
38+
|:-----------|:-----------|
39+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
40+
41+
## Request body
42+
43+
Don't supply a request body for this method.
44+
45+
## Response
46+
47+
If successful, this method returns a `204 No Content` response code. It doesn't return anything in the response body.
48+
49+
This method can return any of the [HTTP status codes](/graph/errors). The most common errors that apps should handle for this method are the 403 and 404 responses. For more information about these errors, see [Common Planner error conditions](../resources/planner-overview.md#common-planner-error-conditions).
50+
51+
## Example
52+
53+
### Request
54+
55+
The following example shows a request.
56+
57+
<!-- {
58+
"blockType": "request",
59+
"name": "delete_plannertaskchatmessage",
60+
"sampleKeys": ["01gzSlKkIUSUl6DF_EilrmQAKDhh", "5bde7bc8-d998-4e8a-8159-93d4d7ccc3b5"]
61+
}-->
62+
```http
63+
DELETE https://graph.microsoft.com/beta/planner/tasks/01gzSlKkIUSUl6DF_EilrmQAKDhh/messages/5bde7bc8-d998-4e8a-8159-93d4d7ccc3b5
64+
```
65+
66+
### Response
67+
68+
The following example shows the response.
69+
70+
<!-- {
71+
"blockType": "response",
72+
"truncated": true
73+
} -->
74+
```http
75+
HTTP/1.1 204 No Content
76+
```
77+
78+
<!-- {
79+
"type": "#page.annotation",
80+
"description": "Delete plannerTaskChatMessage",
81+
"keywords": "",
82+
"section": "documentation",
83+
"tocPath": ""
84+
}-->

0 commit comments

Comments
 (0)