News from Build 2020: Send message to channel moves from beta to 1.0, now support attachments

Coinciding with Build 2020, sending messages to a specific channel has been promoted from the Graph beta endpoint to 1.0. Alongside, it has also gained the ability to add an attachment to a message.

Full details are now published in the 1.0 Graph documentation, but some interesting details below:

There is a new permission, ChannelMessage.Send, which can be used to control this activity. Alternatively, Group.ReadWrite.All can also be used.

There are a few things you can do with this endpoint. You send plain text, but you can also do @mentions, cards, and now attachments.

At Mentions

To @mention someone in a message, you reference the mention by id and then add an entry to the <mentions> branch:

[sourcecode]
POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/messages
Content-type: application/json

{
"body": {
"contentType": "html",
"content": "Hello World &lt;at id=\"0\"&gt;Jane Smith&lt;/at&gt;"
},
"mentions": [
{
"id": 0,
"mentionText": "Jane Smith",
"mentioned": {
"user": {
"displayName": "Jane Smith",
"id": "ef1c916a-3135-4417-ba27-8eb7bd084193",
"userIdentityType": "aadUser"
}
}
}
]
}
[/sourcecode]

Cards

Similar to doing mentions, except that instead of a simple ID, the ID should be a GUID, and then be used in both the body and the attachments section:

[sourcecode]
POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/messages
Content-type: application/json

{
"subject": null,
"body": {
"contentType": "html",
"content": "&lt;attachment id=\"74d20c7f34aa4a7fb74e2b30004247c5\"&gt;&lt;/attachment&gt;"
},
"attachments": [
{
"id": "74d20c7f34aa4a7fb74e2b30004247c5",
"contentType": "application/vnd.microsoft.card.thumbnail",
"contentUrl": null,
"content": "{\r\n \"title\": \"This is an example of posting a card\",\r\n \"subtitle\": \"
&lt;h3&gt;This is the subtitle&lt;/h3&gt;

\",\r\n \"text\": \"Here is some body text.
\\r\\nAnd a &lt;a href=\\\"http://microsoft.com/\\\"&gt;hyperlink&lt;/a&gt;.
\\r\\nAnd below that is some buttons:\",\r\n \"buttons\": [\r\n {\r\n \"type\": \"messageBack\",\r\n \"title\": \"Login to FakeBot\",\r\n \"text\": \"login\",\r\n \"displayText\": \"login\",\r\n \"value\": \"login\"\r\n }\r\n ]\r\n}",
"name": null,
"thumbnailUrl": null
}
]
}
[/sourcecode]

Attachments

Adding an attachment is similar to adding a card – slightly confusingly both are considered an ‘attachment’ to the message. The difference is with the contentType that is used: for file attachments the contentType is reference with a URL that points to the content.

To add a file attachment, you need to perform a GET of the driveItem and read the eTag, webUrl of the driveItem folder, and the driveItem name. Then, use those values in the attachment of the message, as below:

[sourcecode]
POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/messages
Content-type: application/json

{
"body": {
"contentType": "html",
"content": "Here’s the latest budget. &lt;attachment id=\"{eTagUrl}\"&gt;&lt;/attachment&gt;"
},
"attachments": [
{
"id": "{eTagUrl}",
"contentType": "reference",
"contentUrl": "{webUrl}/{driveItem name}",
"name": "{driveItem name}"
}
]
}

[/sourcecode]

Throttling

Developers planning on using this API call should be aware of the throttling limits.

This call isn’t designed for data migration scenarios – and the rate limits highlight that. From the published throttling limits, there is a limit of 2 requests per second, per app, per tenant for sending messages, or a cross-app limit for the entire tenant of 20 rps. In addition, there is a hard limit of 3000 messages per app per day that can be sent to a given channel.