W tym poście chciałbym podzielić się z Tobą moimi najnowszymi odkryciami na temat sposobów, w jakie można wzmiankować wszystko w Microsoft Teams wysyłając wiadomości z Power Automate, niezależnie od tego, czy jest to użytkownik, tag, kanał czy zespół.

Wbudowane wzmiankowanie

W Power Automate dostępne są dedykowane akcje, które pozwalają wzmiankować użytkownika lub tag.

Akcje „Get an @mention token for a user” oraz „Get an @mention token for a tag”. Te dwie akcje zwracają tokeny, które można użyć w dowolnej innej akcji, która wysyła wiadomość do Microsoft Teams, na przykład „Post adaptive card in a chat or channel” lub „Post message in a chat or channel”:

Ważne! Token @mention dla tagu może być używany tylko wtedy, gdy karta adaptacyjna lub wiadomość są publikowane przy użyciu kontekstu użytkownika. Wzmiankowanie tagu nie będzie działać w kontekście bota.

Musisz tylko dodać tokeny do swoich kart lub wiadomości:

Wzmiankowanie korzystając z property msteams w Adaptive Card JSON

Drugim podejściem, którego możesz użyć, jest skorzystanie z właściwości msteams, którą można dodać na końcu karty adaptacyjnej wysłanej do Microsoft Teams. Przy okazji – ta właściwość może pomóc w wielu innych scenariuszach (źródło: Text formatting in cards – Teams | Microsoft Docs).

Dlaczego miałbyś to robić w ten sposób nie poprzez akcje @mention, nie wiem, ale podkreślam, że w ten sposób nie udało mi się wspomnieć o tagach, kanałach i zespołach. Chociaż „link” do kanału był wyświetlany na wysłanej karcie, nie zachowywał się prawidłowo, ponieważ najechanie kursorem nie rozwijało szczegółów kanału.

{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
        {
            "type": "TextBlock",
            "id": "MentionTextBlock",
            "text": "Fun with mentions!",
            "weight": "Bolder",
            "size": "Medium"
        },
        {
            "type": "TextBlock",
            "text": "This is user mention. Hi: <at>USER NAME</at>!",
            "size": "Medium"
        }
        {
            "type": "TextBlock",
            "text": "And this mentions tag <at>TAG NAME</at>!",
            "size": "Medium"
        },
        {
            "type": "TextBlock",
            "text": "This is channel mention. Hello: <at>CHANNEL NAME</at>!",
            "size": "Medium"
        }
    ],
    "msteams": {
        "entities": [
            {
                "type": "mention",
                "text": "<at>USER NAME</at>",
                "mentioned": {
                    "id": "8:orgid:USER AAD ID",
                    "name": "USER NAME"
                }
            }
            {
                "type": "mention",
                "text": "<at>TAG NAME</at>",
                "mentioned": {
                    "id": "TAG ID",
                    "name": "TAG NAME"
                }
            },
            {
                "type": "mention",
                "text": "<at>CHANNEL NAME</at>",
                "mentioned": {
                    "id": "CHANNEL ID",
                    "displayName": "CHANNEL NAME",
                    "conversationIdentityType": "channel"
                }
            }
        ]
    }
}

Ważne! By wzmiankować użytkownika musisz dodać prefix 8:orgid: przed wartością Azure AAD ID.

Co ważne, z powyższej metody mogłem skorzystać jedynie przy wysyłaniu kart w kontekście bota. Podczas korzystania z kontekstu użytkownika, akcja cały czas kończyła się błędem: „Message mention text needs to be specified.”. Bez względu na to, jak formatowałem obiekty wzmianek, nie mogłem tego rozwiązać. Więc się poddałem. Jeśli wiesz, jak sprawić by to zadziałało, napisz w komentarzach 🙂

Wzmiankowanie korzystając z webhook kanału

Po pierwsze, aby utworzyć webhooka do kanału, musisz przejść do menu „Connectors” w obrębie kanału:

Następnie skonfiguruj webhooka i skopiuj jego adres URL. Gdy to zrobisz, możesz użyć i skonfigurować akcję HTTP:

Musi to być żądanie POST wysłane do webhooka kanału. A w kwestii zawartości:

{
    "type": "message",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.4",
          "body": [
            {
              "type": "TextBlock",
              "id": "MentionTextBlock",
              "text": "Fun with mentions!",
              "weight": "Bolder",
              "size": "Medium"
            },
            {
              "type": "TextBlock",
              "text": "This is user mention. Hi: <at>USER NAME</at>!",
              "size": "Medium"
            },
            {
              "type": "TextBlock",
              "text": "And this mentions tag <at>TAG NAME</at>!",
              "size": "Medium"
            },
            {
              "type": "TextBlock",
              "text": "This is channel mention. Hello: <at>CHANNEL NAME</at>!",
              "size": "Medium"
            }
          ],
          "msteams": {
            "entities": [
              {
                "type": "mention",
                "text": "<at>USER NAME</at>",
                "mentioned": {
                  "id": "8:orgid:USER AAD ID",
                  "name": "USER NAME"
                }
              },
              {
                "type": "mention",
                "text": "<at>TAG NAME</at>",
                "mentioned": {
                  "id": "TAG ID",
                  "name": "TAG NAME"
                }
              },
              {
                "type": "mention",
                "text": "<at>CHANNEL NAME</at>",
                "mentioned": {
                  "id": "CHANNEL ID",
                  "displayName": "CHANNEL NAME",
                  "conversationIdentityType": "channel",
                  "conversationIdentityType@odata.type": "#Microsoft.Teams.GraphSvc.conversationIdentityType"
                }
              }
            ]
          }
        }
      }
    ]
  }

Tutaj znowu, jak widać, używana jest właściwość msteams. W tym podejściu generowane są wszystkie wzmianki.

Mimo to moim zdaniem nie działają. Ponieważ kiedy najeżdżam na któryś z nich, nie wyświetla żadnych szczegółów, a wiadomość nie jest podświetlana jako wzmianka o mnie. Jeśli to dla Ciebie działa, daj mi proszę znać.

Ważne! Karty adaptacyjne wysyłane przez webhook nie pozwalają na wykonywanie żadnych czynności związanych z przesyłaniem (submit). Jeśli więc planujesz dodać formularz do karty, który użytkownicy mogą wypełnić i wysłać, przy takim podejściu nie będziesz w stanie odebrać odpowiedzi.

Wzmiankowanie używając GraphAPI

W tym podejściu wysyłasz Adaptive Card do endpointa GraphAPI: /beta/teams/team-id/channels/channel-id/messages. Wiecej szczegółów na temat tego podejścia znajdziesz tutaj: Send chatMessage in a channel or a chat – Microsoft Graph beta | Microsoft Docs.

Robię to za pomocą akcji o nazwie „Send an HTTP request” z grupy akcji „Office 365 Groups”. Czemu? Ponieważ jest to czynność standardowa, więc nie wymaga dodatkowej licencji. Możesz osiągnąć to samo, używając akcji „Invoke an HTTP Request” z grupy „HTTP with Azure AD”. Jednak ta jest akcją premium.

Kod, który należy wysłać, składa się z następujących sekcji:

1. Body – zawiera strukturę HTML, w tym miejsce na załącznik, którym w tym przypadku będzie karta adaptacyjna.
2. Attachments – ta właściwość zawiera wyescapeowany kod JSON karty Adaptive Card.
3. Mentions – ta właściwość zawiera obiekty wzmianek, dla każdego identyfikatora wzmianki obecnego w treści karty adaptacyjnej lub we właściwości Body -> Content.

{
    "subject": "Adaptive Cards test",
    "body": {
        "contentType": "html",
        "content": "<attachment id=\"AttachmentID\"></attachment>"
    },
    "attachments": [
        {
            "id": "AttachmentID",
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": "{\r\n  \"$schema\": \"http://adaptivecards.io/schemas/adaptive-card.json\",\r\n  \"type\": \"AdaptiveCard\",\r\n  \"version\": \"1.4\",\r\n  \"body\": [\r\n    {\r\n      \"type\": \"TextBlock\",\r\n      \"id\": \"MentionTextBlock\",\r\n      \"text\": \"Fun with mentions!\",\r\n      \"weight\": \"Bolder\",\r\n      \"size\": \"Medium\"\r\n    },\r\n    {\r\n      \"type\": \"TextBlock\",\r\n      \"text\": \"This is user mention. Hi: <at id=\\\"0\\\">USER NAME</at>!\",\r\n      \"size\": \"Medium\"\r\n    },\r\n    {\r\n      \"type\": \"TextBlock\",\r\n      \"text\": \"This is channel mention. Hello: <at id=\\\"1\\\">CHANNEL NAME</at>!\",\r\n      \"size\": \"Medium\"\r\n    },\r\n    {\r\n      \"type\": \"TextBlock\",\r\n      \"text\": \"This is team mention. Hello: <at id=\\\"2\\\">TEAM NAME</at>!\",\r\n      \"size\": \"Medium\"\r\n    },\r\n    {\r\n      \"type\": \"TextBlock\",\r\n      \"text\": \"This mentions tag <at id=\\\"3\\\">TAG NAME</at>!\",\r\n      \"size\": \"Medium\"\r\n    }\r\n  ]\r\n}",
            "name": null,
            "thumbnailUrl": null
        }
    ],
    "mentions": [
        {
            "id": 0,
            "mentionText": "USER NAME",
            "mentioned": {
                "user": {
                    "id": "USER AAD ID",
                    "displayName": "USER NAME",
                    "userIdentityType": "aadUser"
                }
            }
        },
        {
            "id": 1,
            "mentionText": "CHANNEL NAME",
            "mentioned": {
                "conversation": {
                    "id": "CHANNEL ID",
                    "displayName": "CHANNEL NAME",
                    "conversationIdentityType": "channel"
                }
            }
        },
        {
            "id": 2,
            "mentionText": "TEAM NAME",
            "mentioned": {
                "conversation": {
                    "id": "TEAM ID",
                    "displayName": "TEAM NAME",
                    "conversationIdentityType": "team"
                }
            }
        },
        {
            "id": 3,
            "mentionText": "TAG NAME",
            "mentioned": {
                "tag": {
                    "id": "TAG ID",
                    "displayName": "TAG NAME"
                }
            }
        }
    ]
}

W ten sposób można naprawdę wzmiankować wszystko i działa to dla wszystkich typów wzmianek. A to dlatego, że akcja działa w kontekście użytkownika. Jeśli chcesz wysłać ją w kontekście aplikacji, musisz użyć akcji HTTP i podać szczegóły aplikacji usługi Azure AD, aby uwierzytelnić wywołanie.

Ważne! Wysłane w ten sposób karty adaptacyjne nie pozwolą na wykonanie akcji przesyłania (submit). Jeśli planujesz umożliwić użytkownikom przesyłanie formularzy wysłanych w Adaptive Cards, musisz wybrać inne podejście.

I to wszystko! Ufam, że uznasz to za przydatne.

Materiały

Kilka przydatnych linków, które pomogły mi lepiej zrozumieć jak wzmiankować w Microsoft Teams:

• Send chatMessage in a channel or a chat – Microsoft Graph beta | Microsoft Docs
• Text formatting in cards – Teams | Microsoft Docs
• Channel/Teams mention in Adaptive Cards – Power Platform Community (microsoft.com)
• Solved: Ms Teams @ Mentions in adaptive cards – Power Platform Community (microsoft.com)
• Mention a channel with Flow – Expiscornovus