Mercurial > prosody-modules

annotate mod_muc_inject_mentions/README.markdown @ 4230:495a23d61418

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_prebind: Stop hardcoding test domain
author Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
date Sun, 25 Oct 2020 18:01:25 +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 ```