Microsoft Teams
95 min
the microsoft teams connector allows for the automation of team communication and collaboration tasks, facilitating efficient incident response and management within the swimlane platform microsoft teams is a widely used communication platform that enables collaboration through chat, meetings, and file sharing the microsoft teams connector for swimlane turbine allows users to automate key communication tasks within their security workflows by integrating with microsoft teams, swimlane turbine users can streamline incident response, coordinate team actions, and share critical information directly within the teams environment, enhancing the overall efficiency and response time of security operations prerequisites to utilize the microsoft teams connector for swimlane turbine, ensure you have the following prerequisites oauth 2 0 client credentials authentication with these parameters url endpoint for microsoft teams api access client id application (client) id registered in azure ad client secret secret generated for the registered application token url url to obtain the oauth2 token scopes permissions required for the connector to interact with microsoft teams oauth 2 0 password credentials authentication with these parameters url endpoint for microsoft teams api access oauth2 username username for oauth2 authentication oauth2 password password for oauth2 authentication token url url to obtain the oauth2 token client id application (client) id registered in azure ad scopes permissions required for the connector to interact with microsoft teams oauth 2 0 refresh token authentication with these parameters url endpoint for microsoft teams api access and so on capabilities in order to use actions within this connector you need to ensure you have created a microsoft teams team , you can use the create team action the microsoft teams integration provides the following capabilities using the microsoft graph api add member to channel add member to team create channel create chat create team get channel filesfolder get chat by id get one on one chat for user list channel messages list chats list chats by user id list messages in a chat list pinnedchatmessages in a chat pin a message in a chat reply channel message and so on additional information about graph api features certain actions within microsoft teams and the microsoft graph api are considered protected apis https //docs microsoft com/en us/graph/teams protected apis you can request access here https //docs microsoft com/en us/graph/teams protected apis to use oauth2's delegated authentication webhook considerations in order to post messages to a channel in microsoft teams you must get the webhook url of your channel https //sankalpit com/how to get channel webhook url/ first you will use the url when creating the asset for the action microsoft graph considerations in order to use most actions within this connector, you must define the appropriate scopes for the action you are using below are a list of the action and their required scopes when registering an application in microsoft azure delegated permissions per task add members to a channel channelmember readwrite all add members to a team teammember readwrite all create channel channel create channel create group directory readwrite all group readwrite all teamwork migrate all create team directory readwrite all group readwrite all team create teamwork migrate all and so on asset setup microsoft graph setup steps to create the azure app go to the app registration page https //portal azure com/#blade/microsoft aad registeredapps/applicationslistblade in the azure portal click new registration enter a name for your new application and choose accounts in this organizational directory only , then click register at the bottom navigate to the api permissions tab on the left navigation menu select add a permission select microsoft graph select application permissions or delegated permissions , then mark all the permissions you need for the actions you are using (see suggested permissions at the top of the asset setup section) click the add permissions button at the bottom of the page select grant admin consent for your organization, then your permissions should look as below navigate to the certificates & secrets tab and select new client secret fill out the description and expiration, then click the add button at the bottom the value of the secret you just created is the client secret needed for the swimlane asset 14\ navigate to the overview tab on the left menu 15\ the client id and tenant id needed in the asset are shown on this page authentication the connector can be authenticated in one of two ways oauth 2 0 resource owner password credentials, which require a username , password , token url and client id for more information, click here https //learn microsoft com/en us/azure/active directory/develop/v2 oauth ropc oauth 2 0 client credentials flow, which requires a client id , client secret and token url for more information, click here https //learn microsoft com/en us/azure/active directory/develop/v2 oauth2 client creds grant flow oauth 2 0 refresh token grant, which requires a 'refresh token', 'tenant id', 'client id' and 'client secret' use this auth with accounts which have mfa enabled to generate a refresh token please follow the instructions below in step 3 of the above mentioned setup instructions, please provide a 'redirect uri' and select the platform as 'web', before clicking on 'register' at the the bottom proceed with the remaining steps to generate 'client id', 'tenant id' and 'client secret' the swimlane team will provide a python script and instructions on how to use the script to generate the refresh token configurations ms teams client credentials authenticates using oauth 2 0 client credentials configuration parameters parameter description type required url a url to the target host string required token url string required client id the client id string required client secret the client secret string required scope permission scopes for this action array required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional ms teams password grant authenticates using oauth 2 0 password credentials configuration parameters parameter description type required url a url to the target host string required token url string required oauth2 username the username for authentication string required oauth2 password the password for authentication string required client id the client id string required client secret the client secret string optional scope permission scopes for this action array required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional ms teams refresh token grant authenticates using refresh token use this authentication for accounts with mfa enabled configuration parameters parameter description type required url a url to the target host string required tenant id string required cl id the client id string required cl secret the client secret string required refresh token refresh token string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add member to channel adds a new member to a private or shared microsoft teams channel, requiring team and channel ids, roles, and user binding endpoint url v1 0/teams/{{team id}}/channels/{{channel id}}/members method post input argument name type required description team id string required unique identifier channel id string required unique identifier @odata type string required response data roles array required parameter for add member to channel user\@odata bind string required response data output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata type string response data id string unique identifier roles array output field roles displayname string name of the resource visiblehistorystartdatetime string time value userid string unique identifier email object output field email tenantid string unique identifier example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "b60b398a aa14 41a6 a2db e05e5230ad4e", "client request id" "b60b398a aa14 41a6 a2db e05e5230ad4e", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 22 17 57 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "@odata type" "#microsoft graph aaduserconversationmember", "id" "mcmjmimjzjvknznjngmtymizzc00mjfilthizwutndi0ote2ytrhy2nhiymxoto5n2u3mtc2ngzkymu0 ", "roles" \[], "displayname" "hernan testing account 1", "visiblehistorystartdatetime" "0001 01 01t00 00 00z", "userid" "3987e15d f439 44e5 aa80 590fe116c266", "email" null, "tenantid" "f5d73c4c bb3d 421b 8bee 424916a4acca" } } ] create channel creates a new channel within a specified team in microsoft teams, requiring the team's id as a path parameter endpoint url v1 0/teams/{{team id}}/channels method post input argument name type required description team id string required unique identifier displayname string optional name of the resource description string optional parameter for create channel membershiptype string optional type of the resource @odata type string optional response data members array optional parameter for create channel @odata type string optional response data user\@odata bind string optional response data roles array optional parameter for create channel @microsoft graph channelcreationmode string optional parameter for create channel createddatetime string optional time value output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier createddatetime string time value displayname string name of the resource description string output field description isfavoritebydefault boolean output field isfavoritebydefault email string output field email weburl string url endpoint for the request membershiptype string type of the resource example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "956b7f1f cbe3 4478 bb64 d983f244a469", "client request id" "956b7f1f cbe3 4478 bb64 d983f244a469", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "fri, 27 jan 2023 20 50 18 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "id" "19\ f60f6c45847b45469c5269ab87677648\@thread tacv2", "createddatetime" "2023 01 27t20 50 18 6865201z", "displayname" "test c1c9df65 1934 4a18 a556 b532726215db", "description" "this channel is where we debate all future architecture plans", "isfavoritebydefault" false, "email" "", "weburl" "https //teams microsoft com/l/channel/19%3af60f6c45847b45469c5269ab87677648%40th ", "membershiptype" "standard" } } ] get channel filesfolder retrieve metadata for the storage location of files within a specified microsoft teams channel, requiring team and channel ids endpoint url v1 0/teams/{{team id}}/channels/{{channel id}}/filesfolder method get input argument name type required description team id string required unique identifier channel id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier createddatetime string time value lastmodifieddatetime string time value name string name of the resource weburl string url endpoint for the request size number output field size parentreference object output field parentreference driveid string unique identifier drivetype string type of the resource filesysteminfo object output field filesysteminfo createddatetime string time value lastmodifieddatetime string time value folder object output field folder childcount number count value example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "95c5fefe 5c82 4364 b3d4 fa3223d4b5fb", "client request id" "95c5fefe 5c82 4364 b3d4 fa3223d4b5fb", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 19 54 29 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "id" "01hchocod26wp3c55ixbaiokriauzsa5cg", "createddatetime" "0001 01 01t00 00 00z", "lastmodifieddatetime" "2022 03 29t21 25 00z", "name" "general", "weburl" "https //swimlaneintegrations sharepoint com/sites/integrationsteamtest/shared%20 ", "size" 0, "parentreference" {}, "filesysteminfo" {}, "folder" {} } } ] list channel messages retrieve messages from a specified microsoft teams channel, excluding replies requires 'team id' and 'channel id' endpoint url v1 0/teams/{{team id}}/channels/{{channel id}}/messages method get input argument name type required description team id string required unique identifier channel id string required unique identifier $top number optional parameter for list channel messages $expand number optional parameter for list channel messages output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data @odata nextlink string response data value array value for the parameter id string unique identifier replytoid object unique identifier etag string output field etag messagetype string type of the resource createddatetime string time value lastmodifieddatetime string time value lastediteddatetime object time value deleteddatetime object time value subject object output field subject summary object output field summary chatid object unique identifier importance string output field importance locale string output field locale weburl string url endpoint for the request policyviolation object output field policyviolation eventdetail object output field eventdetail @odata type string response data teamid string unique identifier teamdescription string output field teamdescription example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "956b7f1f cbe3 4478 bb64 d983f244a469", "client request id" "956b7f1f cbe3 4478 bb64 d983f244a469", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "fri, 27 jan 2023 20 50 18 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('fbe2bf47 16c8 47cf b4a5 4b9b18 ", "@odata count" 3, "@odata nextlink" "https //graph microsoft com/v1 0/teams/fbe2bf47 16c8 47cf b4a5 4b9b187c508b/chan ", "value" \[] } } ] reply channel message send a reply to a specific message within a microsoft teams channel, requiring the team id, channel id, message id, and message body endpoint url v1 0/teams/{{team id}}/channels/{{channel id}}/messages/{{message id}}/replies method post input argument name type required description team id string required unique identifier channel id string required unique identifier message id string required unique identifier attachments array optional parameter for reply channel message content string optional response content contenttype string optional type of the resource contenturl string optional url endpoint for the request id string optional unique identifier name string optional name of the resource teamsappid string optional unique identifier thumbnailurl string optional url endpoint for the request body object required request body data content string required response content contenttype string optional type of the resource channelidentity object optional unique identifier channelid string optional unique identifier teamid string optional unique identifier chatid string optional unique identifier createddatetime string optional time value deleteddatetime string optional time value etag string optional parameter for reply channel message from object optional parameter for reply channel message application object optional parameter for reply channel message device object optional parameter for reply channel message conversation object optional parameter for reply channel message output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier replytoid string unique identifier etag string output field etag messagetype string type of the resource createddatetime string time value lastmodifieddatetime string time value lastediteddatetime object time value deleteddatetime object time value subject object output field subject summary object output field summary chatid object unique identifier importance string output field importance locale string output field locale weburl string url endpoint for the request policyviolation object output field policyviolation eventdetail object output field eventdetail from object output field from application object output field application device object output field device user object output field user id string unique identifier displayname string name of the resource example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "3bd868dd 1843 45b0 b08b 516f1ef2e8df", "client request id" "3bd868dd 1843 45b0 b08b 516f1ef2e8df", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 21 28 04 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "id" "1675286885524", "replytoid" "1675286007879", "etag" "1675286885524", "messagetype" "message", "createddatetime" "2023 02 01t21 28 05 524z", "lastmodifieddatetime" "2023 02 01t21 28 05 524z", "lastediteddatetime" null, "deleteddatetime" null, "subject" null, "summary" null, "chatid" null, "importance" "normal", "locale" "en us", "weburl" "https //teams microsoft com/l/message/19%3a85bd7e9fe7ef45b68aaf8ec40b2bc238%40th " } } ] send message to channel sends a new chatmessage to a specified channel in microsoft teams, requiring the 'channel id' and 'team id' endpoint url v1 0/teams/{{team id}}/channels/{{channel id}}/messages method post input argument name type required description channel id string required unique identifier team id string required unique identifier attachments array optional parameter for send message to channel content string optional response content contenttype string optional type of the resource contenturl string optional url endpoint for the request id string optional unique identifier name string optional name of the resource teamsappid string optional unique identifier thumbnailurl string optional url endpoint for the request body object optional request body data content string required response content contenttype string optional type of the resource channelidentity object optional unique identifier channelid string optional unique identifier teamid string optional unique identifier chatid string optional unique identifier createddatetime string optional time value deleteddatetime string optional time value etag string optional parameter for send message to channel from object optional parameter for send message to channel application object optional parameter for send message to channel device object optional parameter for send message to channel conversation object optional parameter for send message to channel user object optional parameter for send message to channel output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier replytoid object unique identifier etag string output field etag messagetype string type of the resource createddatetime string time value lastmodifieddatetime string time value lastediteddatetime object time value deleteddatetime object time value subject object output field subject summary object output field summary chatid object unique identifier importance string output field importance locale string output field locale weburl string url endpoint for the request policyviolation object output field policyviolation eventdetail object output field eventdetail from object output field from application object output field application device object output field device user object output field user id string unique identifier displayname string name of the resource example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "c5d3a593 789e 4fb9 93b6 00ab6fca5b6d", "client request id" "c5d3a593 789e 4fb9 93b6 00ab6fca5b6d", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 21 13 27 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "id" "1675286007879", "replytoid" null, "etag" "1675286007879", "messagetype" "message", "createddatetime" "2023 02 01t21 13 27 879z", "lastmodifieddatetime" "2023 02 01t21 13 27 879z", "lastediteddatetime" null, "deleteddatetime" null, "subject" null, "summary" null, "chatid" null, "importance" "normal", "locale" "en us", "weburl" "https //teams microsoft com/l/message/19%3a85bd7e9fe7ef45b68aaf8ec40b2bc238%40th " } } ] create chat initiates a new chat in microsoft teams with specified members and chat type requires 'chattype' and 'members' in the json body endpoint url v1 0/chats method post input argument name type required description chattype string required type of the resource members array required parameter for create chat @odata type string optional response data roles array optional parameter for create chat user\@odata bind string optional response data output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier topic object output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource weburl string url endpoint for the request tenantid string unique identifier viewpoint object output field viewpoint onlinemeetinginfo object output field onlinemeetinginfo example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //graph microsoft com", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "87834acd 0fba 48de 81f9 82f4db05f650", "client request id" "87834acd 0fba 48de 81f9 82f4db05f650", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 19 44 08 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats/$entity", "id" "19 2b77f477 3a9f 4823 a882 6fb6cae8c7f9 835a7a96 2e57 4e22 858a 2d0b0d63d3f8\@unq ", "topic" null, "createddatetime" "2023 02 01t19 44 08 7z", "lastupdateddatetime" "2023 02 01t19 44 08 7z", "chattype" "oneonone", "weburl" "https //teams microsoft com/l/chat/19%3a2b77f477 3a9f 4823 a882 6fb6cae8c7f9 835 ", "tenantid" "f5d73c4c bb3d 421b 8bee 424916a4acca", "viewpoint" null, "onlinemeetinginfo" null } } ] send message to chat sends a new chat message to a specified microsoft teams chat using the 'chat id' and message 'body' endpoint url v1 0/chats/{{chat id}}/messages method post input argument name type required description chat id string required unique identifier attachments array optional parameter for send message to chat content string optional response content contenttype string optional type of the resource contenturl string optional url endpoint for the request id string optional unique identifier name string optional name of the resource teamsappid string optional unique identifier thumbnailurl string optional url endpoint for the request body object required request body data content string required response content contenttype string optional type of the resource channelidentity object optional unique identifier channelid string optional unique identifier teamid string optional unique identifier chatid string optional unique identifier createddatetime string optional time value deleteddatetime string optional time value etag string optional parameter for send message to chat from object optional parameter for send message to chat application object optional parameter for send message to chat device object optional parameter for send message to chat conversation object optional parameter for send message to chat user object optional parameter for send message to chat id string optional unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier replytoid object unique identifier etag string output field etag messagetype string type of the resource createddatetime string time value lastmodifieddatetime string time value lastediteddatetime object time value deleteddatetime object time value subject object output field subject summary object output field summary chatid string unique identifier importance string output field importance locale string output field locale weburl object url endpoint for the request channelidentity object unique identifier policyviolation object output field policyviolation eventdetail object output field eventdetail from object output field from application object output field application device object output field device user object output field user id string unique identifier example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/chats('19 2b77f477 3a9f 4823 a882 6f ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "1e213b7f a48e 4632 90b6 5ab2d6498b97", "client request id" "1e213b7f a48e 4632 90b6 5ab2d6498b97", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 21 20 43 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats('19%3a2b77f477 3a9f 4823 a882 6 ", "id" "1675286443998", "replytoid" null, "etag" "1675286443998", "messagetype" "message", "createddatetime" "2023 02 01t21 20 43 998z", "lastmodifieddatetime" "2023 02 01t21 20 43 998z", "lastediteddatetime" null, "deleteddatetime" null, "subject" null, "summary" null, "chatid" "19 2b77f477 3a9f 4823 a882 6fb6cae8c7f9 835a7a96 2e57 4e22 858a 2d0b0d63d3f8\@unq ", "importance" "normal", "locale" "en us", "weburl" null } } ] get chat by id retrieve details of a specific chat in microsoft teams using the unique chat id endpoint url v1 0/chats/{{chat id}} method get input argument name type required description chat id string required unique identifier expand string optional parameter for get chat by id output parameter type description status code number http status code of the response odata version string response data date string date value reason string response reason phrase @odata context string response data id string unique identifier topic string output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource weburl string url endpoint for the request tenantid string unique identifier onlinemeetinginfo object output field onlinemeetinginfo viewpoint object output field viewpoint ishidden boolean unique identifier lastmessagereaddatetime string response message example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //graph microsoft com", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "87834acd 0fba 48de 81f9 82f4db05f650", "client request id" "87834acd 0fba 48de 81f9 82f4db05f650", "x ms ags diagnostic" {} }, "odata version" "4 0", "date" "wed, 01 feb 2023 19 44 08 gmt", "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats/$entity", "id" "19\ b8577894a63548969c5c92bb9c80c5e1\@thread v2", "topic" "test group 1", "createddatetime" "2021 04 06t19 49 52 431z", "lastupdateddatetime" "2021 04 06t19 54 04 306z", "chattype" "group", "weburl" "https //teams microsoft com/l/chat/19%3ab8577894a63548969c5c92bb9c80c5e1\@thread ", "tenantid" "b33cbe9f 8ebe 4f2a 912b 7e2a427f477f", "onlinemeetinginfo" null, "viewpoint" {} } } ] get one on one chat for user retrieves a specific one on one chat for a user in microsoft teams using the provided user id and chat id endpoint url v1 0/users/{{user id}}/chats/{{chat id}} method get input argument name type required description user id string required unique identifier chat id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier topic object output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource weburl string url endpoint for the request tenantid string unique identifier onlinemeetinginfo object output field onlinemeetinginfo viewpoint object output field viewpoint ishidden boolean unique identifier lastmessagereaddatetime string response message example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "dce591ab 03d2 4108 9425 3f28f44601ef", "client request id" "dce591ab 03d2 4108 9425 3f28f44601ef", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south india\\",\\"slice\\" \\"e\\",\\"ring\\" \\"2\\",\\"scaleunit\\" \\"00 ", "date" "wed, 31 jan 2024 04 46 13 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats/$entity", "id" "19 8b081ef6 4792 4def b2c9 c363a1bf41d5 877192bd 9183 47d3 a74c 8aa0426716cf\@unq ", "topic" null, "createddatetime" "2019 04 18t23 51 42 099z", "lastupdateddatetime" "2019 04 18t23 51 43 255z", "chattype" "oneonone", "weburl" "https //teams microsoft com/l/chat/19%3a8b081ef6 4792 4def b2c9 c363a1bf41d5 877 ", "tenantid" "2432b57b 0abd 43db aa7b 16eadd115d34", "onlinemeetinginfo" null, "viewpoint" {} } } ] list chats retrieve a list of chat conversations for the currently logged in user in microsoft teams, available with delegated authentication endpoint url v1 0/chats/ method get input argument name type required description $expand string optional parameter for list chats $top number optional parameter for list chats $filter string optional parameter for list chats $orderby string optional parameter for list chats output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data value array value for the parameter id string unique identifier topic object output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource weburl string url endpoint for the request tenantid string unique identifier onlinemeetinginfo object output field onlinemeetinginfo viewpoint object output field viewpoint ishidden boolean unique identifier lastmessagereaddatetime string response message example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "75b62b4f b645 4a6a 9b6f 10330ef25269", "client request id" "75b62b4f b645 4a6a 9b6f 10330ef25269", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south india\\",\\"slice\\" \\"e\\",\\"ring\\" \\"2\\",\\"scaleunit\\" \\"00 ", "odata version" "4 0", "date" "fri, 02 feb 2024 10 29 04 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats", "@odata count" 17, "value" \[] } } ] list chats by user id retrieve a list of chat conversations associated with a specified microsoft teams user id endpoint url v1 0/users/{{user id}}/chats/ method get input argument name type required description user id string required unique identifier $expand string optional parameter for list chats by user id $top number optional parameter for list chats by user id $filter string optional parameter for list chats by user id $orderby string optional parameter for list chats by user id output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data value array value for the parameter id string unique identifier topic object output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource weburl string url endpoint for the request tenantid string unique identifier onlinemeetinginfo object output field onlinemeetinginfo viewpoint object output field viewpoint ishidden boolean unique identifier lastmessagereaddatetime string response message example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "90cdf9d9 4e8d 4fec 9556 d3d796378d70", "client request id" "90cdf9d9 4e8d 4fec 9556 d3d796378d70", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south india\\",\\"slice\\" \\"e\\",\\"ring\\" \\"2\\",\\"scaleunit\\" \\"00 ", "odata version" "4 0", "date" "fri, 02 feb 2024 10 49 24 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats", "@odata count" 17, "value" \[] } } ] list messages in a chat retrieve a list of messages from a specified chat in microsoft teams using the chat id endpoint url /v1 0/chats/{{chat id}}/messages method get input argument name type required description chat id string required unique identifier $top number optional parameter for list messages in a chat $orderby string optional parameter for list messages in a chat $filter string optional parameter for list messages in a chat output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data @odata nextlink string response data value array value for the parameter id string unique identifier replytoid object unique identifier etag string output field etag messagetype string type of the resource createddatetime string time value lastmodifieddatetime string time value lastediteddatetime object time value deleteddatetime object time value subject object output field subject summary object output field summary chatid string unique identifier importance string output field importance locale string output field locale weburl object url endpoint for the request channelidentity object unique identifier policyviolation object output field policyviolation eventdetail object output field eventdetail from object output field from application object output field application example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "be6e1664 c548 43c2 af1f db4ab3c2ed16", "client request id" "be6e1664 c548 43c2 af1f db4ab3c2ed16", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south india\\",\\"slice\\" \\"e\\",\\"ring\\" \\"2\\",\\"scaleunit\\" \\"00 ", "odata version" "4 0", "date" "mon, 05 feb 2024 08 22 08 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats('19%3ac608788699d3482bba51b83a1 ", "@odata count" 5, "@odata nextlink" "https //graph microsoft com/v1 0/chats/19\ c608788699d3482bba51b83a1120b1c0\@threa ", "value" \[] } } ] list pinnedchatmessages in a chat retrieve all pinned chat messages from a specified microsoft teams chat using the chat id endpoint url /chats/{{chat id}}/pinnedmessages method get input argument name type required description chat id string required the id of the chat $expand number optional parameter for list pinnedchatmessages in a chat output parameter type description status code number http status code of the response reason string response reason phrase value array value for the parameter @odata type string response data id string unique identifier example \[ { "status code" 200, "reason" "ok", "json body" { "value" \[] } } ] pin a message in a chat pins a specified message within an existing microsoft teams chat using the chat's id requires an existing chat id endpoint url /chats/{{chat id}}/pinnedmessages method post input argument name type required description chat id string required the id of the chat headers object optional headers content type string required the content type of the request output parameter type description status code number http status code of the response reason string response reason phrase @odata type string response data id string unique identifier example \[ { "status code" 201, "reason" "created", "json body" { "@odata type" "#microsoft graph pinnedchatmessageinfo", "id" "1616964509832" } } ] add member to team adds a new member to a specified microsoft teams team, requiring the team's id and member details such as type, roles, and user binding endpoint url v1 0/teams/{{team id}}/members method post input argument name type required description team id string required unique identifier @odata type string required response data roles array required parameter for add member to team user\@odata bind string required response data output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata type string response data id string unique identifier roles array output field roles displayname string name of the resource visiblehistorystartdatetime string time value userid string unique identifier email object output field email tenantid string unique identifier example \[ { "status code" 201, "response headers" { "transfer encoding" "chunked", "content type" "application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=f ", "content encoding" "gzip", "location" "https //teamsgraph teams microsoft com/v1 0/teams('2c435237 2587 4d26 a318 fc853 ", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "c8fbe719 da69 45c7 bc1a f6395c5e8d53", "client request id" "c8fbe719 da69 45c7 bc1a f6395c5e8d53", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "odata version" "4 0", "date" "wed, 01 feb 2023 21 33 44 gmt" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#teams('2c435237 2587 4d26 a318 fc8537 ", "@odata type" "#microsoft graph aaduserconversationmember", "id" "mcmjmsmjzjvknznjngmtymizzc00mjfilthizwutndi0ote2ytrhy2nhiymyyzqzntizny0yntg3ltrk ", "roles" \[], "displayname" "hernan testing account 1", "visiblehistorystartdatetime" "0001 01 01t00 00 00z", "userid" "3987e15d f439 44e5 aa80 590fe116c266", "email" null, "tenantid" "f5d73c4c bb3d 421b 8bee 424916a4acca" } } ] create team creates a new team in microsoft teams with specified details provided in the json body and headers endpoint url v1 0/teams method post input argument name type required description template\@odata bind string optional response data displayname string optional name of the resource description string optional parameter for create team members array optional parameter for create team @odata type string optional response data roles array optional parameter for create team user\@odata bind string optional response data visibility string optional parameter for create team channels array optional parameter for create team displayname string optional name of the resource isfavoritebydefault boolean optional parameter for create team description string optional parameter for create team tabs array optional parameter for create team teamsapp\@odata bind string optional response data displayname string optional name of the resource configuration object optional parameter for create team contenturl string optional url endpoint for the request websiteurl string optional url endpoint for the request membersettings object optional parameter for create team allowcreateupdatechannels boolean optional parameter for create team allowdeletechannels boolean optional parameter for create team allowaddremoveapps boolean optional parameter for create team allowcreateupdateremovetabs boolean optional parameter for create team allowcreateupdateremoveconnectors boolean optional parameter for create team guestsettings object optional parameter for create team output parameter type description status code number http status code of the response reason string response reason phrase response text string output field response text example \[ { "status code" 202, "response headers" { "content location" "/teams('454d3685 9ae8 476d 80fd 2d607e5b8d9d')", "location" "/teams('454d3685 9ae8 476d 80fd 2d607e5b8d9d')/operations('38613ae4 0012 462c b7 ", "strict transport security" "max age=31536000", "request id" "a181d619 2cd5 400e a60c fcde238c8af7", "client request id" "a181d619 2cd5 400e a60c fcde238c8af7", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south central us\\",\\"slice\\" \\"e\\",\\"ring\\" \\"5\\",\\"scaleunit ", "date" "fri, 27 jan 2023 20 10 36 gmt", "content length" "0" }, "reason" "accepted", "response text" "" } ] unpin a message from a chat removes a pinned message from a specified chat in microsoft teams using the chat id and pinnedchatmessageid endpoint url delete /chats/{{chat id}}/pinnedmessages/{{pinnedchatmessageid}} method delete input argument name type required description chat id string required the id of the chat pinnedchatmessageid string required the id of the pinned chat message output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 204, "reason" "no content" } ] update chat updates the topic of a specified chat in microsoft teams using the chat id and a new topic value endpoint url v1 0/chats/{{chat id}} method patch input argument name type required description chat id string required unique identifier topic string required the title of the chat this can only be set for a chat with a chattype value of group maximum length is 250 characters use of ' ' is not allowed output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data id string unique identifier topic string output field topic createddatetime string time value lastupdateddatetime string time value chattype string type of the resource example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "request id" "dce591ab 03d2 4108 9425 3f28f44601ef", "client request id" "dce591ab 03d2 4108 9425 3f28f44601ef", "x ms ags diagnostic" "{\\"serverinfo\\" {\\"datacenter\\" \\"south india\\",\\"slice\\" \\"e\\",\\"ring\\" \\"2\\",\\"scaleunit\\" \\"00 ", "date" "wed, 31 jan 2024 04 46 13 gmt" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/v1 0/$metadata#chats/$entity", "id" "19 1c5b01696d2e4a179c292bc9cf04e63b\@thread v2", "topic" "group chat title update", "createddatetime" "2020 12 04t23 11 16 175z", "lastupdateddatetime" "2020 12 04t23 12 19 943z", "chattype" "group" } } ] response headers header description example client request id http response header client request id 1e213b7f a48e 4632 90b6 5ab2d6498b97 content encoding http response header content encoding gzip content length the length of the response body in bytes 0 content location http response header content location /teams('454d3685 9ae8 476d 80fd 2d607e5b8d9d') content type the media type of the resource application/json date the date and time at which the message was originated fri, 27 jan 2023 20 50 18 gmt location the url to redirect a page to /teams('454d3685 9ae8 476d 80fd 2d607e5b8d9d')/operations('38613ae4 0012 462c b798 b6ea5d7b7489') odata version http response header odata version 4 0 request id http response header request id be6e1664 c548 43c2 af1f db4ab3c2ed16 strict transport security http response header strict transport security max age=31536000 transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding x ms ags diagnostic http response header x ms ags diagnostic {"serverinfo" {"datacenter" "south central us","slice" "e","ring" "5","scaleunit" "002","roleinstance" "sn1pepf0000647f"}} notes for the refresh token auth, the generated refresh token will have 90 days as the default expiry value unless it is reduced by your organization you need to update the asset after the refresh token expires pymsteams module https //github com/rveachkc/pymsteamsmessagecard api https //docs microsoft com/en us/outlook/actionable messages/message card referencemicrosoft graph teamwork apis https //docs microsoft com/en us/graph/api/resources/teams api overview?view=graph rest 1 0 this connector was last tested against product version microsoft graph v1 endpoints