Mercurial > prosody-modules

comparison mod_slack_webhooks/README.markdown @ 3000:02fc3b64cbb7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial commit of mod_slack_webhooks. This provides an HTTP-based interface to and from Prosody-hosted MUCs equivalent to Slack's incoming and outgoing webhook interfaces, allowing a variety of Slack integrations to be used with a Prosody MUC.
author Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
date Sun, 15 Apr 2018 08:45:43 -0700
parents
children 00fc569e8333
comparison
equal deleted inserted replaced
2999:d631fd9a3300 3000:02fc3b64cbb7
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'Allow Slack integrations to work with Prosody MUCs'
5 ...
6
7 Introduction
8 ============
9
10 This module provides a Slack-compatible "web hook" interface to Prosody MUCs.
11 Both "incoming" web hooks, which allow Slack integrations to post messages
12 to Prosody MUCs, and "outgoing" web hooks, which copy messages from Prosody
13 MUCs to Slack-style integrations by HTTP, are supported. This can also be
14 used, in conjunction with various Slack inter-namespace bridging tools, to
15 provide a bidirectional bridge between a Prosody-hosted XMPP MUC and a Slack
16 channel.
17
18 Usage
19 =====
20
21 First copy the module to the prosody plugins directory.
22
23 Then add "slack\_webhooks" to your modules\_enabled list:
24
25 ``` {.lua}
26 Component "conference.example.org" "muc"
27 modules_enabled = {
28 "slack_webhooks",
29 }
30 ```
31
32 Configuration
33 =============
34
35 The normal use for this module is to provide an incoming webhook to allow
36 integrations to post to prosody MUCs:
37
38 ``` {.lua}
39 incoming_webhook_path = "/msg/DFSDF56587658765NBDSA"
40 default_from_nick = "Bot" -- Unless otherwise specified, posts as "Bot"
41 ```
42
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.
44 Specifying a string of random gibberish in the URL is important to prevent spam.
45
46 In addition, there is a second operating mode equivalent to Slack's outgoing
47 webhooks. This allows all messages from a set of specified chat rooms to be
48 routed to an external server over HTTP in the format used by Slack's
49 outgoing webhooks.
50 ``` {.lua}
51 outgoing_webhook_routing = {
52 -- Send all messages from chat@conference.example.org to
53 -- a web server.
54 ["chat"] = "http://example.org/cgi-bin/messagedest",
55 }
56 ```
57
58 Known Issues
59 ============
60
61 The users from whom messages delivered from integrations are apparently
62 delivered are not, in general, members of the MUC. Other prosody modules
63 that try to look up information about the users who most messages, mostly
64 logging modules, may become confused and fail (clients all work fine because
65 replayed history also can come from non-present users). In at least some cases,
66 such as with mod_muc_mam, this can be fixed by hiding the JIDs of the
67 participants in the room configuration.
68
69 There are a few smaller UI issues:
70
71 * If an integration posts with the same username as a room member, there is
72 no indication (like Slack's [bot] suffix) that the message is not from that
73 room member.
74 * It is not currently possible to prevent posting to some MUCs (this is
75 also true of Slack).
76 * It should be possible to set the webhook configuration for a room in the
77 room configuration rather than statically in Prosody's configuration file.
78
79 Compatibility
80 =============
81
82 ------- -----------------
83 trunk Untested
84 0.10 Works
85 0.9 Works
86 ------- -----------------
87