How to use IBM App Connect with Microsoft Teams

Connecting to Microsoft Teams

• If you don't have an Microsoft Teams account, you can sign up to Microsoft Teams for free.

For the considerations and steps you need to connect App Connect on IBM Cloud to a Microsoft Teams account, see Connecting to Microsoft Teams from App Connect on IBM Cloud.

General considerations for using Microsoft Teams in App Connect

• (General consideration) You can see lists of the trigger events and actions that are available on the Catalog page of the App Connect Designer.

  For some applications, the events and actions in the catalog depend on the environment (IBM Cloud Pak for Integration or App Connect on IBM Cloud) and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

• (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.
• Microsoft Azure Active Directory groups are typically created in the Microsoft 365 admin center or in the Microsoft Azure portal. If you have the required permissions, you can use the 'Create group' action in App Connect to create Microsoft 365 groups or security groups.
• If you are using a non-admin user account to connect to Microsoft Teams, you can use App Connect to update or delete groups only if you are the owner of that group.
• When you use the 'Create chat message' or 'Retrieve chat messages' action to create or retrieve chat messages in App Connect, you are required to first select an existing chat from a drop-down list.
  
  • For one-on-one chats with another user whose name is specified in the To field in Microsoft Teams, the chat ID is displayed in the App Connect Chat list in a format similar to this: 19:50144721-4f5b-4765-9b65-fd554a36c65c_8372f761-5d10-4888-ef47-5be0b7315e72@unq.gbl.spaces.
    
  • For group chats (which include the subject of the conversation in the Group name field, and multiple user names in the To field in Microsoft Teams), the Group name (subject) value is displayed in the App Connect Chat list, making the chat easily identifiable.
    

  For ease of identification in App Connect, consider creating your chats with a Group name (subject) value in Microsoft Teams if you intend to frequently use the 'Create chat message' or 'Retrieve chat messages' actions.

• When you use the 'Create message reply' or 'Retrieve message replies' action to create or retrieve message replies in App Connect, you are required to first select a team, channel, and message for the reply. In the Message list, messages that were created with a subject will display the subject value, and messages without a subject will display an ID value that was generated by Microsoft Teams.
  

  If required, you can check which ID is assigned to a message in Microsoft Teams by opening the More options menu (...) for a message and then clicking Copy link. The message ID is included in the link; for example:

  https://teams.microsoft.com/l/message/19:a954b78415a547a7438c354c54b40f30@thread.tacv2/1595593605014?tenantId=0184ab77-1234-4ac0-5678-bf7eec6de925&groupId=e1c2515c-4512-471e-a772-60ce5ba78921&parentMessageId=1595593605014&teamName=FDteam&channelName=General&createdTime=1595593605014

  

  For ease of identification in App Connect, consider creating message replies with a subject in Microsoft Teams if you intend to frequently use the 'Create message reply' or 'Retrieve message replies' actions.

  
• When you use the 'Create chat message', 'Create message', or 'Create message reply' action to create a message or reply in App Connect, you can add an attachment to the message by specifying a content type and associated content. Currently, only rich card attachments are supported. You can use the Content type field to select a card format and then use the Content field to specify a rich card object that defines the JSON format of the card. The supported card attachments are as follows:

  Content type	Description	Content
  application/vnd.microsoft.card.adaptive	An Adaptive card that can contain text, speech, images, buttons, and input fields.	Specify an AdaptiveCard object.
  application/vnd.microsoft.card.hero	A Hero card that can contain a large image, one or more buttons, and some text.	Specify a HeroCard object.
  application/vnd.microsoft.card.thumbnail	A Thumbnail card that can contain a thumbnail image, one or more buttons, and some text.	Specify a ThumbnailCard object.
  application/vnd.microsoft.com.card.receipt	A Receipt card that provides a receipt.	Specify a ReceiptCard object. Restriction: This card currently gives partial output.
  application/vnd.microsoft.com.card.signin	A Sign In card that requests a user to sign in.	Specify a SignInCard object.

  For more information about these card attachments, see Cards Reference in the Microsoft documentation.

  The following examples provide sample JSON for each content type.

  Adaptive card:

  json
  
  {
      "type": "AdaptiveCard",
      "body": [
          {
              "type": "TextBlock",
              "size": "Medium",
              "weight": "Bolder",
              "text": "Profile Info"
          },
          {
              "type": "FactSet",
              "facts": [
                  {
                      "title": "Given name",
                      "value": "John"
                  },
                  {
                      "title": "Surname",
                      "value": "Doe"
                  },
                  {
                      "title": "Job title",
                      "value": "Software Dev"
                  },
                  {
                      "title": "Office location",
                      "value": "NYC"
                  },
                  {
                      "title": "Email",
                      "value": "john@doe.com"
                  }
              ]
          },
          {
              "type": "TextBlock",
              "text": "Business phones",
              "weight": "Bolder"
          },
          {
              "type": "TextBlock",
              "text": "{$data}",
              "$data": "{businessPhones}",
              "spacing": "None"
          }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
      "version": "1.0"
  }

  Hero card:

  json
  {
       "title": "Seattle Center Monorail",
       "subtitle": "Seattle Center Monorail",
       "text": "The Seattle Center Monorail is an elevated train line between Seattle Center (near the Space Needle) and downtown Seattle. It was built for the 1962 World's Fair. Its original two trains, completed in 1961, are still in service.",
       "images": [
         {
           "url":"https://upload.wikimedia.org/wikipedia/commons/thumb/4/49/Seattle_monorail01_2008-02-25.jpg/1024px-Seattle_monorail01_2008-02-25.jpg"
         }
       ],
      "buttons": [
        {
           "type": "openUrl",
           "title": "Official website",
           "value": "https://www.seattlemonorail.com"
         },
        {
          "type": "openUrl",
          "title": "Wikipeda page",
          "value": "https://en.wikipedia.org/wiki/Seattle_Center_Monorail"
         }
       ]
     }

  Thumbnail card:

  json
  {
      "title": "Bender",
      "subtitle": "tale of a robot who dared to love",
      "text": "Bender Bending Rodríguez is a main character in the animated television series Futurama. He was created by series creators Matt Groening and David X. Cohen, and is voiced by John DiMaggio",
      "images": [
        {
          "url": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
          "alt": "Bender Rodríguez"
        }
      ],
      "buttons": [
        {
          "type": "imBack",
          "title": "Thumbs Up",
          "image": "http://moopz.com/assets_c/2012/06/emoji-thumbs-up-150-thumb-autox125-140616.jpg",
          "value": "I like it"
        },
        {
          "type": "imBack",
          "title": "Thumbs Down",
          "image": "http://yourfaceisstupid.com/wp-content/uploads/2014/08/thumbs-down.png",
          "value": "I don't like it"
        },
        {
          "type": "openUrl",
          "title": "I feel lucky",
          "image": "http://thumb9.shutterstock.com/photos/thumb_large/683806/148441982.jpg",
          "value": "https://www.bing.com/images/search?q=bender&qpvt=bender&qpvt=bender&qpvt=bender&FORM=IGRE"
        }
      ],
      "tap": {
        "type": "imBack",
        "value": "Tapped it!"
      }
    }

  Receipt card (Partial):

  json
  {
          "title": "I'm a receipt card",
          "items": [
            {
              "title": "Sushi",
              "subtitle": "2 piece",
              "image": {
                "url": "https://mydeploy.azurewebsites.net/sushi.png"
              },
              "price": "16.25",
              "quantity": "1"
            },
            {
              "title": "Tenpura",
              "subtitle": "1 dish",
              "image": {
                "url": "https://mydeploy.azurewebsites.net/tenpura.jpg"
              },
              "price": "34.50",
              "quantity": "2"
            }
          ],
          "total": "275.25",
          "tax": "27.52",
          "buttons": [
            {
              "type": "openUrl",
              "title": "Go to my site",
              "value": "https://blogs.msdn.microsoft.com/tsmatsuz"
            }
          ]
        }

  Sign In card:

  json
  {
      "buttons": [
          {
              "title": "Log In",
              "type": "openUrl",
              "value": "https://login.microsoftonline.com"
          }
      ],
      "text": "Sign in to our app"
  }

Events and actions

Microsoft Teams events

These events are for changes in this application that trigger a flow to start performing the actions in the flow.

Messages

New message

Updated message

Deleted message

Microsoft Teams actions

These are actions on this application that you want a flow to complete.

Channels

Create channel

Retrieve channels

Update channel

Delete channel

Chat messages

Send chat message

Retrieve chat messages

Chats

Retrieve chats

Groups

Create group

Retrieve groups

Update group

Delete group

Members

Retrieve members

Add member

Delete member

Message replies

Create a reply to message

Retrieve message replies

Messages

Send message to channel

Retrieve messages

Owners

Retrieve owners

Set owner

Delete owner

Teams

Create team

Retrieve teams

Update team

Users

Retrieve users