Mercurial > prosody-modules

annotate mod_slack_webhooks/README.markdown @ 3436:12c7c0d7e1b0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_pubsub_text_interface/README: Fix typo (thanks perflyst)
author Kim Alvefur <zash@zash.se>
date Mon, 07 Jan 2019 19:46:04 +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