hypothesis / hypothesis/slack-annotations
Notify in Slack on `@mention`'s in annotations
- Dominant language
- Python
- Stars
- 2
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
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](https://hypothes-is.slack.com/archives/C4K6M7P5E/p1730970002364089).)
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. https://github.com/hypothesis/slack-annotations/issues/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](https://docs.google.com/document/d/1gmsnocFPIb0MUNPjXauJDXgdHkz7aRGfiPPk7GyEJTc/) 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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.