prosody-modules
fe8222112cf4
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 @ 6199:fe8222112cf4

mod_conversejs: Serve base app at / This makes things slightly less awkward for the browser to figure out which URLs belong to a PWA. The app's "start URL" was previously without the '/' and therefore was not considered within the scope of the PWA. Now the canonical app URL will always have a '/'. Prosody/mod_http should take care of redirecting existing links without the trailing / to the new URL. If you have an installation at https://prosody/conversejs then it is now at https://prosody/conversejs/ (the first URL will now redirect to the second URL if you use it). The alternative would be to make the PWA scope include the parent, i.e. the whole of https://prosody/ in this case. This might get messy if other PWAs are provided by the same site or Prosody installation, however.
author Matthew Wild <mwild1@gmail.com>
date Tue, 11 Feb 2025 13:18:38 +0000
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