Software /
code /
prosody-modules
Annotate
mod_slack_webhooks/README.markdown @ 3436:12c7c0d7e1b0
mod_pubsub_text_interface/README: Fix typo (thanks perflyst)
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Mon, 07 Jan 2019 19:46:04 +0100 |
parent | 3000:02fc3b64cbb7 |
child | 4769:00fc569e8333 |
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 |
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" |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
40 default_from_nick = "Bot" -- Unless otherwise specified, posts as "Bot" |
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 ------- ----------------- |
02fc3b64cbb7
Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff
changeset
|
83 trunk Untested |
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 |