當我們要在 Microsoft Teams 中提到某個人或頻道時，可以用 @ 來標註某個人或頻道，更直接的提醒某人這裡有屬於他的訊息。然而我們要如何在透過 Teams Webhook 發送訊息時達成這樣的提醒呢？這篇來解決這個問題。
這是一個相當多人敲碗的功能。在自動化的驅動之下，我們很多系統的運作訊息會透過通訊軟體 Microsoft Teams 來發送及時訊息，為了能更容易的被特定人士察覺，用 @ 來標註特定人是通訊軟體常見且方便的功能。
要在 Teams Webhook 訊息中標註某個人或頻道，需要基於使用 Adaptive Cards 發送訊息到 Microsoft Teams Webhook的基礎之下做延伸，如此一來，我們可以產生出像是下面這樣的 JSON 內容：
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"body": [
{
"type": "TextBlock",
"text": "Hi <at>mention</at> in Teams Webhook",
}
]
}
}
]
}
在訊息的內容中，可以注意到 <at>mention</at> 這個用 <at> 標籤包住的內容，這個關鍵字串很重要（裡面 mention 字串可以自行修改），接下來的操作會需要搭配這串做對應，讓標註的人能被標註在指定的位置中。
接著，要在 content 這個屬性之中，附加上 msteams 屬性，這個屬性是專屬給 Microsoft Teams 解析的，而裡面的 entities 則是要標註的人有哪些，每個人都需要對應到一組 <at> 標籤內容。因此如果你要標註多人的時候，要加入多組 <at> 標籤，不然會標註失敗。
至於標註誰的關鍵，則是在於 id 的設定值，這個值必須要是當前 Teams 組織內的成員的 Email，name 則是要標註的人的顯示名稱（對！可以修改標註的顯示名稱），效果如下：
而 msteams 這個屬性的 JSON 內容大致上會是像下面這樣：
{
// 略...
"msteams": {
"width": "Full",
"entities": [
{
"type": "mention",
"text": "<at>mention</at>",
"mentioned": {
"id": "poychang@YOUR_ORG_DOMAIN.com",
"name": "poychang"
}
}
]
}
// 略...
}
如果你想要標註的是某個頻道，則需要在該頻道右邊的 ... 選項中，點選 Get email address 取得頻道的專用 Email，再將頻道的專用 Email 填入 id 值中，這樣就可以標註頻道了。
最後來看一下完整的 JSON 內容會長的怎樣：
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"body": [
{
"type": "TextBlock",
"text": "Hi <at>mention</at> in Teams Webhook",
}
],
"msteams": {
"width": "Full",
"entities": [
{
"type": "mention",
"text": "<at>mention</at>",
"mentioned": {
"id": "poychang@YOUR_ORG_DOMAIN.com",
"name": "poychang"
}
}
]
}
}
}
]
}
後記
眼尖的你，可能會注意到 msteams 屬性中，我多加了一個 width 並設定成 Full，這個屬性是讓 Webhook 訊息能把內容區域撐大，不然預設會是行動裝置適合的大小，而在電腦上看該訊息的時候，就會感覺很奇怪。
參考資料：
