author | aidan@jmad.org |
Sun, 25 Feb 2024 18:20:04 -0800 | |
changeset 5880 | c5df6d53f17f |
parent 4773 | 00fc569e8333 |
permissions | -rw-r--r-- |
3004
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 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
18 |
Usage |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
19 |
===== |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
20 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
21 |
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
|
22 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
23 |
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
|
24 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
25 |
``` {.lua} |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
26 |
Component "conference.example.org" "muc" |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
27 |
modules_enabled = { |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
28 |
"slack_webhooks", |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
29 |
} |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
30 |
``` |
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 |
Configuration |
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 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
35 |
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
|
36 |
integrations to post to prosody MUCs: |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
37 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
38 |
``` {.lua} |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
39 |
incoming_webhook_path = "/msg/DFSDF56587658765NBDSA" |
4773
00fc569e8333
mod_slack_webhook: fixed documentation for default nick and marked trunk as works
Gary Kramlich <grim@reaperworld.com>
parents:
3004
diff
changeset
|
40 |
incoming_webhook_default_nick = "Bot" -- Unless otherwise specified, posts as "Bot" |
3004
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
41 |
``` |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
42 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
43 |
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
|
44 |
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
|
45 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
46 |
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
|
47 |
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
|
48 |
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
|
49 |
outgoing webhooks. |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
50 |
``` {.lua} |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
51 |
outgoing_webhook_routing = { |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
52 |
-- 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
|
53 |
-- a web server. |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
54 |
["chat"] = "http://example.org/cgi-bin/messagedest", |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
55 |
} |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
56 |
``` |
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 |
Known Issues |
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 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
61 |
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
|
62 |
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
|
63 |
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
|
64 |
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
|
65 |
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
|
66 |
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
|
67 |
participants in the room configuration. |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
68 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
69 |
There are a few smaller UI issues: |
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 |
* 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
|
72 |
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
|
73 |
room member. |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
74 |
* 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
|
75 |
also true of Slack). |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
76 |
* 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
|
77 |
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
|
78 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
79 |
Compatibility |
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 |
|
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
82 |
------- ----------------- |
4773
00fc569e8333
mod_slack_webhook: fixed documentation for default nick and marked trunk as works
Gary Kramlich <grim@reaperworld.com>
parents:
3004
diff
changeset
|
83 |
trunk Works |
3004
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
84 |
0.10 Works |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
85 |
0.9 Works |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
86 |
------- ----------------- |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
87 |