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.