Notify in Slack on @mention's in annotations

[seanh]

If someone types @seanh in an annotation it would be good if seanh received a mention in Slack when the annotation is posted into Slack.

Challenges:

• When posting annotations into Slack via their API I don't think mentions like @seanh work (although I haven't tested and verified). Based on reading Slack's API docs I think the script would have to post <@U074DEU66> where U074DEU66 is @seanh's Slack member ID. (Related Slack thread.)

  I think the script would have to do something like this:

  1. Parse the annotation text to find any @mention's
  2. For each user who is @mention'd:
     1. Call the Hypothesis API to get info about that user (e.g. their display name)
     2. Call the Slack API to get info about all the users in our Slack organization, including their usernames and display names
     3. Find a Slack user who matches the Hypothesis user, if any, and get that Slack user's member ID. For example maybe there's a Slack user with the same username and/or display name. We could also supplement this with a manual mapping of some Hypothesis users to Slack users when there are people whose user and display names don't match.
     4. Replace the @username's in the annotation with <@MEMBERID>'s before posting it to Slack

• The script doesn't currently call the Slack API at all, so we'd have to add support for that (including whatever is necessary for authentication) to implement the above. This is also needed for other issues e.g. Post annotations quicker #1.

• Hypothesis annotations are in Markdown format, whereas Slack posts use Slack's "mrkdwn" format which is vaguely Markdown-ish but incompatible and clashes with Markdown's syntax. If we posted annotations into Slack as "mrkdwn" then there'd be formatting clashes between Markdown and "mrkdwn" (italics, bold, etc). For this reason the script currently posts annotations as plain text. Even if we replace @username's with <@MEMBERID>'s I'm not sure whether Slack will see those as mentions if we're posting as plain text. I would have to test this to verify, but I think we may need to escape "mrkdown" special characters in the annotation and then post it as "mrkdwn".

Note that we're currently talking about implementing @mention's in Hypothesis itself with in-app notifications in Hypothesis and also email notifications. This may reduce the need for Slack notifications from the script. Also, we may consider extending the planned Hypothesis mentions feature by adding Slack notifications as a core Hypothesis feature.