prosody-modules
06fbbd45ba75
mod_slack_webhooks/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_slack_webhooks/README.md @ 6302:06fbbd45ba75

mod_cloud_notify: Readme: fix links and labels that were removed in the last commit diff --git a/mod_cloud_notify/README.md b/mod_cloud_notify/README.md --- a/mod_cloud_notify/README.md +++ b/mod_cloud_notify/README.md @@ -1,3 +1,9 @@ +---- +-labels: +-- 'Stage-Beta' +-summary: 'XEP-0357: Cloud push notifications' +---- + # Introduction This module enables support for sending "push notifications" to clients @@ -32,15 +38,15 @@ notification to your device. When your d it will display it or wake up the app so it can connect to XMPP and receive any pending messages. -This protocol is described for developers in \[XEP-0357: Push -Notifications\]. +This protocol is described for developers in [XEP-0357: Push +Notifications]. -For this module to work reliably, you must have \[mod_smacks\], -\[mod_mam\] and \[mod_carbons\] also enabled on your server. +For this module to work reliably, you must have [mod_smacks], +[mod_mam] and [mod_carbons] also enabled on your server. Some clients, notably Siskin and Snikket iOS need some additional extensions that are not currently defined in a standard XEP. To support -these clients, see \[mod_cloud_notify_extensions\]. +these clients, see [mod_cloud_notify_extensions]. # Configuration @@ -58,18 +64,18 @@ these clients, see \[mod_cloud_notify_ex # Internal design notes App servers are notified about offline messages, messages stored by -\[mod_mam\] or messages waiting in the smacks queue. The business rules +[mod_mam] or messages waiting in the smacks queue. The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. -To cooperate with \[mod_smacks\] this module consumes some events: +To cooperate with [mod_smacks] this module consumes some events: `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. These events allow this module to send out notifications for messages received while the session is hibernated by -\[mod_smacks\] or even when smacks acknowledgements for messages are +[mod_smacks] or even when smacks acknowledgements for messages are delayed by a certain amount of seconds configurable with the -\[mod_smacks\] setting `smacks_max_ack_delay`. +[mod_smacks] setting `smacks_max_ack_delay`. The `smacks_max_ack_delay` setting allows to send out notifications to clients which aren't already in smacks hibernation state (because the
author Menel <menel@snikket.de>
date Fri, 13 Jun 2025 10:44:37 +0200
parent 6023:dea01d8595af
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
6015
23b48120661d mod_slack_webhooks: README.md: link and footer
Menel <menel@snikket.de>
parents: 6009
diff changeset
18 If you're looking for a more versatile module, consider [mod_rest]
6009
bd9805f3aba1 mod_slack_webhooks: Update compability and note about mod_rest
Menel <menel@snikket.de>
parents: 6003
diff changeset
19
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
20 Usage
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
21 =====
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 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
24
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
25 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
26
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
27 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
28 Component "conference.example.org" "muc"
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
29 modules_enabled = {
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
30 "slack_webhooks",
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 ```
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 Configuration
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
35 =============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
36
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
37 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
38 integrations to post to prosody MUCs:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
39
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
40 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
41 incoming_webhook_path = "/msg/DFSDF56587658765NBDSA"
4769
00fc569e8333 mod_slack_webhook: fixed documentation for default nick and marked trunk as works
Gary Kramlich <grim@reaperworld.com>
parents: 3000
diff changeset
42 incoming_webhook_default_nick = "Bot" -- Unless otherwise specified, posts as "Bot"
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
43 ```
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
44
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
45 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
46 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
47
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
48 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
49 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
50 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
51 outgoing webhooks.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
52 ``` {.lua}
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
53 outgoing_webhook_routing = {
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
54 -- 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
55 -- a web server.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
56 ["chat"] = "http://example.org/cgi-bin/messagedest",
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 ```
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 Known Issues
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
61 ============
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
62
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
63 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
64 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
65 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
66 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
67 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
68 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
69 participants in the room configuration.
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 There are a few smaller UI issues:
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
72
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
73 * 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
74 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
75 room member.
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
76 * 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
77 also true of Slack).
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
78 * 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
79 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
80
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
81 Compatibility
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
6023
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
84 Prosody Version Status
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
85 ----------------- -----------
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
86 trunk[^1] Works
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
87 0.12 Works
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
88 ----------------- -----------
3000
02fc3b64cbb7 Initial commit of mod_slack_webhooks.
Nathan Whitehorn <nwhitehorn@physics.ucla.edu>
parents:
diff changeset
89
6023
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
90 [^1]: as of 2024-10-22
dea01d8595af mod_slack_webhooks: README.md correction
Menel <menel@snikket.de>
parents: 6015
diff changeset
91