Mercurial > prosody-modules

annotate mod_muc_inject_mentions/README.markdown @ 4210:a0937b5cfdcb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites_page: Remove preauth URI button This button is incompatible with the majority of XMPP clients around, yet based on feedback from users, many are drawn to click it when they have any XMPP client installed already. In the case where the user already has software installed, we would prefer them to select it from the software list so they can follow the setup process suited to their specific client (we already track which software supports preauth URIs). If their client is not listed, they can still use the manual registration link instead.
author Matthew Wild <mwild1@gmail.com>
date Fri, 16 Oct 2020 11:03:38 +0100
parents a82b0745383b
children 32b4901a9d8d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4138
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
1 # Introduction
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
2
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
3 This module intercepts messages sent to a MUC, looks in the message's body if a user was mentioned and injects a mention type reference to that user implementing [XEP-0372](https://xmpp.org/extensions/xep-0372.html#usecase_mention)
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
4
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
5 ## Features
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
6
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
7 1. Multiple mentions in the same message using affixes, including multiple mentions to the same user.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
8 Examples:
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
9 `Hello nickname`
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
10 `@nickname hey!`
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
11 `nickname, hi :)`
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
12 `Are you sure @nickname?`
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
13
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
14 2. Mentions are only injected if no mention was found in a message, avoiding this way, injecting mentions in messages sent from clients with mentions support.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
15
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
16 3. Configuration settings for customizing affixes and enabling/disabling the module for specific rooms.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
17
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
18
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
19 # Configuring
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
20
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
21 ## Enabling
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
22
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
23 ```{.lua}
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
24
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
25 Component "rooms.example.net" "muc"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
26
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
27 modules_enabled = {
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
28 "muc_inject_mentions";
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
29 }
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
30
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
31 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
32
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
33 ## Settings
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
34
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
35 Apart from just writing the nick of an occupant to trigger this module,
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
36 common affixes used when mentioning someone can be configured in Prosody's config file.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
37 Recommended affixes:
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
38
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
39 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
40 muc_inject_mentions_prefixes = {"@"} -- Example: @bob hello!
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
41 muc_inject_mentions_suffixes = {":", ",", "!", ".", "?"} -- Example: bob! How are you doing?
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
42 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
43
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
44 This module can be enabled/disabled for specific rooms.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
45 Only one of the following settings must be set.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
46
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
47 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
48 -- muc_inject_mentions_enabled_rooms = {"room@conferences.server.com"}
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
49 -- muc_inject_mentions_disabled_rooms = {"room@conferences.server.com"}
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
50 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
51
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
52 If none or both are found, all rooms in the muc component will have mentions enabled.
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
53
4160
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
54
4161
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
55 By default, if a message contains at least one mention,
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
56 the module does not do anything, as it believes all mentions were already sent by the client.
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
57 In cases where it is desired the module to inspect the message and try to find extra mentions
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
58 that could be missing, the following setting can be added:
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
59
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
60 ```
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
61 muc_inject_mentions_append_mentions = true
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
62 ```
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
63
032e1c79d039 mod_muc_inject_mentions: Add new configuration setting to look for mentions even if the client sent some already
Seve Ferrer <seve@delape.net>
parents: 4160
diff changeset
64
4163
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
65 Prefixes can be removed using:
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
66 ```
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
67 muc_inject_mentions_strip_out_prefixes = true
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
68 ```
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
69 Turning `Hey @someone` into `Hey someone`.
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
70 Currently, prefixes can only be removed from module added mentions.
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
71 If the client sends a mention type reference pointing to a nickname using a prefix (`Hey @someone`), the prefix will not be removed.
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
72
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions
Seve Ferrer <seve@delape.net>
parents: 4161
diff changeset
73
4164
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
74 There are two lists where this module pulls the participants from.
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
75 1. Online participants
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
76 2. Participants with registered nicknames
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
77
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
78 By default, the module will try to find mentions to online participants.
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
79 Using:
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
80 ```
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
81 muc_inject_mentions_reserved_nicks = true
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
82 ```
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
83 Will try to find mentions to participants with registered nicknames.
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
84 This is useful for setups where the nickname is reserved for all participants,
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
85 allowing the module to catch mentions to participants that might not be online at the moment of sending the message.
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
86
a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants
Seve Ferrer <seve@delape.net>
parents: 4163
diff changeset
87
4160
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
88 It is also possible to modify how this module detects mentions.
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
89 In short, the module will detect if a mention is actually a mention
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
90 if the nickname (with or without affixes) is between spaces, new lines, or at the beginning/end of the message.
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
91 This can be changed using:
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
92
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
93 ```
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
94 -- muc_inject_mentions_mention_delimiters = {" ", "", "\n"}
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
95 ```
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
96 Generally speaking and unless the use-case is very specific, there should be no need to modify the defaults of this setting.
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
97
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting
Seve Ferrer <seve@delape.net>
parents: 4138
diff changeset
98
4138
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
99 # Example stanzas
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
100
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
101 Alice sends the following message
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
102
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
103 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
104 <message id="af6ca" to="room@conference.localhost" type="groupchat">
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
105 <body>@bob hey! Are you there?</body>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
106 </message>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
107 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
108
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
109 Then, the module detects `@bob` is a mention to `bob` and injects a mention type reference to him
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
110
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
111 ```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
112 <message from="room@conference.localhost/alice" id="af6ca" to="alice@localhost/ThinkPad" type="groupchat">
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
113 <body>@bob hey! Are you there?</body>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
114 <reference xmlns="urn:xmpp:reference:0"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
115 begin="1"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
116 end="3"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
117 uri="xmpp:bob@localhost"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
118 type="mention"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
119 />
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
120 </message>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository
Seve Ferrer <seve@delape.net>
parents:
diff changeset
121 ```