prosody-modules
9122d5a246c2
mod_slack_webhooks/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_slack_webhooks/README.md @ 6181:9122d5a246c2

mod_groups_internal: Update groups_muc_host config documentation
author Rémi Bardon <remi@remibardon.name>
date Fri, 31 Jan 2025 02:11:42 +0100
parent 6023:dea01d8595af
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
1 ---
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
2 labels:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
3 - 'Stage-Alpha'
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
4 summary: 'Allow Slack integrations to work with Prosody MUCs'
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
5 ...
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
6
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
7 Introduction
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
8 ============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
9
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
10 This module provides a Slack-compatible "web hook" interface to Prosody MUCs.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
11 Both "incoming" web hooks, which allow Slack integrations to post messages
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
12 to Prosody MUCs, and "outgoing" web hooks, which copy messages from Prosody
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
13 MUCs to Slack-style integrations by HTTP, are supported. This can also be
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
14 used, in conjunction with various Slack inter-namespace bridging tools, to
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
15 provide a bidirectional bridge between a Prosody-hosted XMPP MUC and a Slack
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
16 channel.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
17
6015
23b48120661d mod_slack_webhooks: README.md: link and footer
Menel <menel@snikket.de>
parents: 6009
diff changeset
18 If you're looking for a more versatile module, consider [mod_rest]
6009
bd9805f3aba1 mod_slack_webhooks: Update compability and note about mod_rest
Menel <menel@snikket.de>
parents: 6003
diff changeset
19
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
20 Usage
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
21 =====
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
22
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
23 First copy the module to the prosody plugins directory.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
24
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
25 Then add "slack\_webhooks" to your modules\_enabled list:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
26
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
27 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
28 Component "conference.example.org" "muc"
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
29 modules_enabled = {
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
30 "slack_webhooks",
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
31 }
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
32 ```
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
33
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
34 Configuration
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
35 =============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
36
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
37 The normal use for this module is to provide an incoming webhook to allow
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
38 integrations to post to prosody MUCs:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
39
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
40 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
41 incoming_webhook_path = "/msg/DFSDF56587658765NBDSA"
4769
00fc569e8333 mod_slack_webhook: fixed documentation for default nick and marked trunk as works
Gary Kramlich <grim@reaperworld.com>
parents: 3000
diff changeset
42 incoming_webhook_default_nick = "Bot" -- Unless otherwise specified, posts as "Bot"
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
43 ```
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
44
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
45 This allows Slack-style JSON messages posted to http://conference.example.org/msg/DFSDF56587658765NBDSA/chat to appear in the MUC chat@conference.example.org. A username field in the message is honored as the nick attached to the message; if no username is specified, the message will use the value of default_from_nick.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
46 Specifying a string of random gibberish in the URL is important to prevent spam.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
47
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
48 In addition, there is a second operating mode equivalent to Slack's outgoing
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
49 webhooks. This allows all messages from a set of specified chat rooms to be
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
50 routed to an external server over HTTP in the format used by Slack's
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
51 outgoing webhooks.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
52 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
53 outgoing_webhook_routing = {
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
54 -- Send all messages from chat@conference.example.org to
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
55 -- a web server.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
56 ["chat"] = "http://example.org/cgi-bin/messagedest",
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
57 }
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
58 ```
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
59
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
60 Known Issues
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
61 ============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
62
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
63 The users from whom messages delivered from integrations are apparently
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
64 delivered are not, in general, members of the MUC. Other prosody modules
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
65 that try to look up information about the users who most messages, mostly
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
66 logging modules, may become confused and fail (clients all work fine because
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
67 replayed history also can come from non-present users). In at least some cases,
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
68 such as with mod_muc_mam, this can be fixed by hiding the JIDs of the
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
69 participants in the room configuration.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
70
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
71 There are a few smaller UI issues:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
72
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
73 * If an integration posts with the same username as a room member, there is
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
74 no indication (like Slack's [bot] suffix) that the message is not from that
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
75 room member.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
76 * It is not currently possible to prevent posting to some MUCs (this is
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
77 also true of Slack).
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
78 * It should be possible to set the webhook configuration for a room in the
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
79 room configuration rather than statically in Prosody's configuration file.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
80
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
81 Compatibility
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
82 =============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
83
6023
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
84 Prosody Version Status
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
85 ----------------- -----------
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
86 trunk[^1] Works
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
87 0.12 Works
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
88 ----------------- -----------
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
89
6023
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
90 [^1]: as of 2024-10-22
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
91