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:
POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/messages Content-type: application/json { "body": { "contentType": "html", "content": "Hello World <at id=\"0\">Jane Smith</at>" }, "mentions": [ { "id": 0, "mentionText": "Jane Smith", "mentioned": { "user": { "displayName": "Jane Smith", "id": "ef1c916a-3135-4417-ba27-8eb7bd084193", "userIdentityType": "aadUser" } } } ] }
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:
POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/messages Content-type: application/json { "subject": null, "body": { "contentType": "html", "content": "<attachment id=\"74d20c7f34aa4a7fb74e2b30004247c5\"></attachment>" }, "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\": \" <h3>This is the subtitle</h3> \",\r\n \"text\": \"Here is some body text. \\r\\nAnd a <a href=\\\"http://microsoft.com/\\\">hyperlink</a>. \\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 } ] }
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:
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. <attachment id=\"{eTagUrl}\"></attachment>" }, "attachments": [ { "id": "{eTagUrl}", "contentType": "reference", "contentUrl": "{webUrl}/{driveItem name}", "name": "{driveItem name}" } ] }
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.