Mercurial > prosody-modules

annotate mod_slack_webhooks/README.markdown @ 4211:0f26ae2f2a74

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites_page: Change client selection button text from 'Install' to 'Select' by default This also allows specific clients entries to override the text via the 'select_text' field. Rationale: 1) users may already have the software installed, we still want them to select it anyway for the tailored setup experience. 2) some clients (e.g. web clients) are not really "installed" so the text was misleading
author Matthew Wild <mwild1@gmail.com>
date Fri, 16 Oct 2020 11:06:25 +0100
parents 02fc3b64cbb7
children 00fc569e8333
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
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