{"id":5313,"date":"2020-09-22T10:38:19","date_gmt":"2020-09-22T17:38:19","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=5313"},"modified":"2020-09-22T10:38:19","modified_gmt":"2020-09-22T17:38:19","slug":"change-notifications-for-microsoft-teams-messages-now-generally-available","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/change-notifications-for-microsoft-teams-messages-now-generally-available\/","title":{"rendered":"Change Notifications for Microsoft Teams Messages now Generally Available"},"content":{"rendered":"

Back in February we announced the public preview of change notifications for Teams messages and we are excited to share we have now moved the change notification for Teams to general availability<\/a>. This was one of the most common requests made in UserVoice, and we heard it from developers who wanted to listen to Teams messages in near-real time, without polling, to enable scenarios such as data loss prevention, enterprise information archiving, and bots that listen to messages that they aren’t @mentioned on. We’re excited to tell you change notifications for Teams messages are now generally available, and you can now subscribe to change notifications<\/a> on v1.0 endpoint of Microsoft Graph API.<\/p>\n

Using the Microsoft Graph POST \/subscriptions<\/a> API, developers can subscribe to messages in a particular channel (\/teams\/{id}\/channels\/{id}\/messages<\/a>) or in a particular 1:1 or group chat thread (\/chats\/{id}\/messages<\/a>). You can hear about new messages, replies, edits, reactions, and deletes.<\/p>\n

Developers can also subscribe to all messages in a tenant. This requires the creation of two subscriptions: one for the \/teams\/getAllMessages<\/a> resource and one for \/chats\/getAllMessages. With the general availability of change notifications for Teams messages, \/teams\/getAllMessages and \/chats\/getAllMessages become part of the E5 value for customers, see our list of<\/p>\n

As with all Microsoft Graph webhooks, creating a subscription starts with passing in the URL of the webhook you wish Graph to call back to, and validating the subscription creation within your web service. When a new message arrives, Graph will send that message to your webhook. Teams messages<\/a> are the first Graph resource to support webhooks with resource data<\/a>, so you don\u2019t need to make a second API call to retrieve the message text.<\/p>\n

Example \u2014 setting up a Teams message subscription:<\/p>\n

POST https:\/\/graph.microsoft.com\/beta\/subscriptions\n{\n    \"resource\": \"teams\/97edf8ce-b0f5-4bc8-91e8-7c73185f18c0\/channels\/19:945129d1eede4536a6a9811e71d7b2a6@thread.skype\/messages\",\n    \"notificationUrl\": \"https:\/\/apps.contoso.com\/messageswebhookhandler\",\n    \"changeType\": \"created,updated,deleted\",\n    \"clientState\": \"6b5acd8b-98d1-48be-a8be-e12842fadcd5\",\n    \"expirationDateTime\": \"2020-02-13T01:33:09.1416264Z\",\n    \"encryptionCertificate\": \"MIIDNDCCAhygAwIBAgIQLR3AKZYNS42E....\",\n    \"encryptionCertificateId\": \"70ffad80b880496a968e83091174a979\",\n    \"includeResourceData\": \"True\"\n}<\/pre>\n
Example response<\/p>\n
HTTP\/1.1 201 Created\n{\n    \"@odata.context\": \"https:\/\/graph.microsoft.com\/v1.0\/$metadata#subscriptions\/$entity\",\n    \"id\": \"da94613a-d11a-41e2-b635-295a59b29f3b\",\n    \"resource\": \"teams\/97edf8ce-b0f5-4bc8-91e8-7c73185f18c0\/channels\/19:945129d1eede4536a6a9811e71d7b2a6@thread.skype\/messages\",\n    \"notificationUrl\": \"https:\/\/apps.contoso.com\/messageswebhookhandler\",\n    \"applicationId\": \"7ad2eb86-67bc-42a1-bb7b-04659985e51e\",\n    \"changeType\": \"created,updated\",\n    \"clientState\": \"ClientSecret\",\n    \"lifecycleNotificationUrl\": null,\n    \"expirationDateTime\": \"2020-02-13T01:33:09.1416264Z\",\n    \"creatorId\": \"dfe1df92-51cf-4f68-be9c-87be7c1b447d\",\n    \"includeResourceData\": true,\n    \"encryptionCertificate\": \"MIIDNDCCAhygAwIBAgIQLR3AKZYNS42E....\",\n    \"encryptionCertificateId\": \"70ffad80b880496a968e83091174a979\"\n}<\/pre>\n
After you request the subscription, Microsoft Graph will ping your URL to confirm that wants notifications. As subsequent messages are updated, you will see requests to your web services that look as follows:<\/p>\n
POST https:\/\/apps.contoso.com\/messageswebhookhandler\n{\n    \"body\": {\n        \"contentType\": \"text\",\n        \"content\": \"Hello world!\"\n    },\n    \"id\": \"1581554024315\",\n    \"replyToId\": \"1581553690121\",\n    \"etag\": \"1581554024315\",\n    \"messageType\": \"message\",\n    \"createdDateTime\": \"2020-02-13T00:33:44Z\",\n    \"lastModifiedDateTime\": null,\n    \"deletedDateTime\": null,\n    \"subject\": null,\n    \"summary\": null,\n    \"importance\": \"normal\",\n    \"locale\": \"en-us\",\n    \"webUrl\": \"\",\n    \"from\": {\n        \"application\": null,\n        \"device\": null,\n        \"user\": {\n            \"id\": \"7ed20f7a-09c6-4a47-8ebf-a6a1f2588624\",\n            \"displayName\": \"Megan Bowen\",\n            \"userIdentityType\": \"aadUser\"\n        },\n        \"conversation\": null\n    },\n    \"attachments\": [],\n    \"mentions\": [],\n    \"policyViolation\": null,\n    \"reactions\": [],\n    \"replies\": [],\n    \"hostedContents\": []\n}<\/pre>\n
Decrypting the encryptedContent gives the full message details:<\/p>\n
{\n    \"body\": {\n        \"contentType\": \"text\",\n        \"content\": \"Hello world!\"\n    },\n    \"id\": \"1581554024315\",\n    \"replyToId\": \"1581553690121\",\n    \"etag\": \"1581554024315\",\n    \"messageType\": \"message\",\n    \"createdDateTime\": \"2020-02-13T00:33:44Z\",\n    \"lastModifiedDateTime\": null,\n    \"deletedDateTime\": null,\n    \"subject\": null,\n    \"summary\": null,\n    \"importance\": \"normal\",\n    \"locale\": \"en-us\",\n    \"webUrl\": \"\",\n    \"from\": {\n        \"application\": null,\n        \"device\": null,\n        \"user\": {\n            \"id\": \"7ed20f7a-09c6-4a47-8ebf-a6a1f2588624\",\n            \"displayName\": \"Megan Bowen\",\n            \"userIdentityType\": \"aadUser\"\n        },\n        \"conversation\": null\n    },\n    \"attachments\": [],\n    \"mentions\": [],\n    \"policyViolation\": null,\n    \"reactions\": [],\n    \"replies\": [],\n    \"hostedContents\": []\n}<\/pre>\n
Data loss prevention PATCH<\/h3>\n
After examining a message, apps can mark a message as noncompliant<\/a> with organizational policy and hide that message from view.<\/p>\n
PATCH \/teams\/{id}\/channels\/{id}\/messages\/{id}\n{\n    \"policyViolation\": {\n        \"dlpAction\": \"BlockAccess\",\n        \"verdictDetails\": \"AllowFalsePositiveOverride\",\n        \"policyTip\": {\n            \"generalText\": \"Don't\u00a0share\u00a0credit\u00a0card\u00a0numbers!\",\n            \"complianceUrl\": \"https:\/\/contoso.com\/dlp-policy-page\",\n            \"matchedConditionDescriptions\": [\n                \"Credit\u00a0Card\u00a0Number\"\n            ]\n        }\n    }\n}<\/pre>\n
Next steps<\/h3>\n
You can get started by trying out the sample app<\/a>.\u00a0 See the documentation<\/a> for more information about Microsoft Teams messaging webhooks.<\/p>\n
If you have any feedback about or suggestions for these APIs, please let us know via User Voice<\/a> (under Teamwork).<\/p>\n
Happy coding!<\/p>\n
<\/h3>\n","protected":false},"excerpt":{"rendered":"
Back in February we announced the public preview of change notifications for Teams messages and we are excited to share we have now moved the change notification for Teams to general availability. This was one of the most common requests made in UserVoice, and we heard it from developers who wanted to listen to Teams […]<\/p>\n","protected":false},"author":69096,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3,128],"tags":[],"class_list":["post-5313","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","category-microsoft-teams"],"acf":[],"blog_post_summary":"
Back in February we announced the public preview of change notifications for Teams messages and we are excited to share we have now moved the change notification for Teams to general availability. This was one of the most common requests made in UserVoice, and we heard it from developers who wanted to listen to Teams […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5313","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69096"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=5313"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5313\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=5313"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=5313"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=5313"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}