Add initial support for user mentions

[atc0005]

I've not yet tested to determine if it works in our environment, but as noted on atc0005/go-teams-notify#127, the following curl/JSON recipe can be used to target a specific user when posting to a Teams channel via webhook URL:

curl -X POST -H "Content-type: application/json" -d '{
    "type": "message", 
    "text": "Hey <at>Some User</at> check out this message",
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"some.user@company.com",
                "name":"Some User"
            },
            "text": "<at>Some User</at>"
        }
    ]
}' <webhook_url>

Need to start prototyping changes to this tool and the library to support that functionality.

[atc0005]

For this JSON block:

{
    "type": "message", 
    "text": "Hey <at>Some User</at> check out this message",
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"some.user@company.com",
                "name":"Some User"
            },
            "text": "<at>Some User</at>"
        }
    ]
}

Is the <at>...</at> text needed, or is it just used for formatting? If it's needed, is it needed at both places?

e.g.,

1. "text": "Hey <at>Some User</at> check out this message",
   • the first text key/value
2. "text": "<at>Some User</at>"
   • the key/value for entities

[atc0005]

When attempting to find the minimum required syntax, I found that failing to provide the <at>Some User</a> portion of the message text value resulted in this response:

Webhook message delivery failed with error: Microsoft Teams endpoint returned HTTP error 400 with ContextId MS-CV=z4ufBXevF0iTilVdhweKBA.0..

The HTTP respone code still appears to be 200 however. For a successful submission (and mention of target user), a body response of 1 still occurs. This is when submitting a test message via webhook using the full JSON example noted in the OP.

[atc0005]

Some potentially relevant official documentation:

• https://docs.microsoft.com/en-us/answers/questions/493820/teams-incomming-webhook-mention.html
• https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format?tabs=adaptive-md%2Cconnector-html#user-mention-in-incoming-webhook-with-adaptive-cards
• https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#send-adaptive-cards-using-an-incoming-webhook
• https://docs.microsoft.com/en-us/powershell/module/azuread/get-azureaduser?view=azureadps-2.0
• https://adaptivecards.io/explorer/

Example of an ID:

• 2b450b8e-1db6-42cb-a545-1b05eb8a358b

Example of a User Principal Name (UPN):

• NewTestUser@contoso.onmicrosoft.com

[atc0005]

Accepting (for now) that this is the minimal JSON payload required to produce a message that mentions a user:

{
    "type": "message", 
    "text": "Hey <at>Some User</at> check out this message",
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"some.user@company.com",
                "name":"Some User"
            },
            "text": "<at>Some User</at>"
        }
    ]
}

I can see how we would populate all values easily enough except for this one:

    "text": "Hey <at>Some User</at> check out this message",

If we accept a raw value directly from the user, do we parse the text and require that ...

• <a> and </a> are present
• that a user-specified placeholder string (e.g., PLACEHOLDER) is present

If the latter, we can search/replace against that placeholder and drop in the username (shown as name in the JSON payload) wrapped with <a> and </a> tags.

If the former, we leave the text as-is.

Perhaps the behavior can be configurable:

• if a --mention-user-placeholder (example flag name) flag is specified, don't require that <a> and </a> are present if the --mention-user-name and --mention-user-id flags are used
• if the --mention-user-name and --mention-user-id flags are used without specifying the --mention-user-placeholder flag, require that <a> and </a> are present in the user-specified message text string.

[atc0005]

When attempting to find the minimum required syntax, I found that failing to provide the <at>Some User</a> portion of the message text value resulted in this response:

Webhook message delivery failed with error: Microsoft Teams endpoint returned HTTP error 400 with ContextId MS-CV=z4ufBXevF0iTilVdhweKBA.0..

Per https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-and-group-conversations?tabs=json#work-with-mentions:

The text field in the object in the entities array must match a portion of the message text field. If it does not, the mention is ignored.

[atc0005]

Note to self:

Look back at https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-and-group-conversations?tabs=typescript#work-with-mentions later for inspiration regarding handling the text field (duplication of content in entity and the standalone text field).

[atc0005]

Accepting (for now) that this is the minimal JSON payload required to produce a message that mentions a user:

The go-teams-notify project currently implements much of the MessageCard format, but not yet the Adaptive Card format.

The JSON payload appears to follow the Adaptive Card format, but the entities element is not nested inside of a msteams element as expected. I also don't see either listed here: https://adaptivecards.io/explorer/

[atc0005]

The JSON payload appears to follow the Adaptive Card format, but the entities element is not nested inside of a msteams element as expected. I also don't see either listed here: https://adaptivecards.io/explorer/

https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-and-group-conversations?tabs=json#retrieve-mentions provides example JSON in that format (trimmed):

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
}

This doesn't appear to be in either of Adaptive Card or MessageCard format. Is this a third format?

Per https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#adaptive-card:

Adaptive, hero, list, Office 365 Connector, receipt, signin, and thumbnail cards and card collections are supported in bots for Microsoft Teams. They are based on cards defined by the Bot Framework, but Teams does not support all Bot Framework cards and has added some of its own.

Perhaps validation is lax and Teams isn't rejecting JSON payloads that don't completely meet the Adaptive Card format?

[atc0005]

This doesn't appear to be in either of Adaptive Card or MessageCard format. Is this a third format?

Per further discussion on atc0005/go-teams-notify#127 and additional reading, perhaps the sample JSON payload is a third format. I'll refer to it for now using the suggested name of "bot api".

I'm going to prototype changes to the atc0005/go-teams-notify project involving the creation of a new "sub" package named botapi. Instead of reproducing the existing API functionality in its entirety, I'm thinking about creating unexported versions of the necessary functions. These functions can accept an interface in place of the MessageCard type that the exported functions currently require which can allow them to accept either MessageCard or botapi.Message types as appropriate, rejecting all others. Not sure yet.

Worst case, I can replicate all required functionality for the time being as internal/unexported functionality which can be refactored later. This may be the least complicated route to take for now.

More to come.

[atc0005]

I'm going to prototype changes to the atc0005/go-teams-notify project involving the creation of a new "sub" package named botapi.

See also atc0005/go-teams-notify#149.

The prototyping work is surfacing enough limitations that I'm strongly leaning towards exposing the teamsClient directly (e.g., goteamsnotify.TeamsClient) instead of publishing versioned API (e.g., APIv2, APIv3) interfaces.

[atc0005]

I'm going to prototype changes to the atc0005/go-teams-notify project involving the creation of a new "sub" package named botapi.

See also atc0005/go-teams-notify#149.

The prototyping work is surfacing enough limitations that I'm strongly leaning towards exposing the teamsClient directly (e.g., goteamsnotify.TeamsClient) instead of publishing versioned API (e.g., APIv2, APIv3) interfaces.

This is the direction I went.

Because the "botapi" package will be an incomplete representation of the actual bot api and because it doesn't support all of the features of the MessageCard format, in many ways using the bot api will be a step backwards. If someone opts to generate a user mention (message) using this tool they're implicitly opting out of several existing settings:

• message title
• message theme color
• message trailer (app responsible for generating a message that send2teams delivers)

Granted, this is probably not a big deal; I am unsure which approach is better:

1. emit warnings when these options are specified alongside user mention(s)
2. use config validation to reject these flags paired with user mention(s)

I'd ordinarily think of the first approach in order to be backwards compatible, but using the user mention support would be an intentional choice and a good time for the app to surface incompatibilities between the settings.

All of that said, once Adaptive Card support is added to the atc0005/go-teams-notify library it is likely that it will act as a superset for the existing MessageCard functionality. This suggests that emitting warnings for a mix of incompatible settings would be a better approach as a near-term hotfix. I could link to a GH issue that explains in more detail, or refer the user to the README file (likely a better approach).

[atc0005]

This suggests that emitting warnings for a mix of incompatible settings would be a better approach as a near-term hotfix.

I'm actually leaning towards emitting errors for incompatible settings. Users will opt into using user mention support and it would be good to explicitly note what options do not work well together.

[atc0005]

I think I've got the initial prototype where it needs to be for a test/dev release. Still rough edges and no doc updates yet to reflect the changes.

I also have some more cleanup work to do for the bundled local changes atc0005/go-teams-notify library before I push them upstream (for further polish/iteration). Hoping to get that done before week's end.

[atc0005]

I also have some more cleanup work to do for the bundled local changes atc0005/go-teams-notify library before I push them upstream (for further polish/iteration). Hoping to get that done before week's end.

Latest changes have been pushed upstream and local prototype updated to use them.

Aiming for an alpha release of both the prototype of this CLI app and the atc0005/go-teams-notify library by week's end.

[atc0005]

Aiming for an alpha release of both the prototype of this CLI app and the atc0005/go-teams-notify library by week's end.

Library update available here:

https://github.com/atc0005/go-teams-notify/releases/tag/v2.7.0-alpha.1