prosody-modules: mod_muc_inject_mentions/README.markdown@39c2824c2880 (annotated)

4142 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
4316 33a41503b9e3 Improve UX by providing defaults users expect Seve Ferrer <seve@delape.net> parents: 4257 diff changeset	52	If none of these is set, all rooms in the muc component will have mentions enabled.
4142 e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	53
4164 9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 diff changeset	54
4165 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 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: 4164 diff changeset	64
4167 320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions Seve Ferrer <seve@delape.net> parents: 4165 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: 4165 diff changeset	66	```
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions Seve Ferrer <seve@delape.net> parents: 4165 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: 4165 diff changeset	68	```
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions Seve Ferrer <seve@delape.net> parents: 4165 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: 4165 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: 4165 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: 4165 diff changeset	72
320f6d374b5d mod_muc_inject_mentions: Add new configuration setting to strip out prefixes from mentions Seve Ferrer <seve@delape.net> parents: 4165 diff changeset	73
4168 a82b0745383b mod_muc_inject_mentions: Add new configuration setting to choose between registered nicknames or online participants Seve Ferrer <seve@delape.net> parents: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 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: 4167 diff changeset	87
4164 9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 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: 4142 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: 4142 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: 4142 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: 4142 diff changeset	92
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 diff changeset	93	```
4257 32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	94	-- muc_inject_mentions_mention_delimiters = {" ", "", "\n", "\t"}
4164 9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 diff changeset	95	```
9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 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: 4142 diff changeset	97
4257 32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	98	When triggering a mention must only happen if that mention includes a prefix, this can be configured with:
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	99	```
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	100	-- muc_inject_mentions_prefix_mandatory = true
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	101	```
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	102
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	103	By default, mentions use the bare jid of the participant as the URI attribute.
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	104	If the MUC jid of the participant (eg. room@chat.example.org/Romeo) is preferred, this can be set using:
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	105	```
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	106	-- muc_inject_mentions_use_real_jid = false
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	107	```
32b4901a9d8d mod_muc_inject_mentions: Add new setting to trigger mentions only if a prefix is found Seve Ferrer <seve@delape.net> parents: 4168 diff changeset	108
4164 9626d5d1adc4 mod_muc_inject_mentions: Update README explainig mention_delimiters setting Seve Ferrer <seve@delape.net> parents: 4142 diff changeset	109
4142 e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	110	# Example stanzas
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	Alice sends the following message
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	113
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	114	```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	115	<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	116	<body>@bob hey! Are you there?</body>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	117	</message>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	118	```
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	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	121
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	122	```
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	123	<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	124	<body>@bob hey! Are you there?</body>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	125	<reference xmlns="urn:xmpp:reference:0"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	126	begin="1"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	127	end="3"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	128	uri="xmpp:bob@localhost"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	129	type="mention"
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	130	/>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	131	</message>
e8c1b35bc25b mod_muc_inject_mentions: Publish module to repository Seve Ferrer <seve@delape.net> parents: diff changeset	132	```

author	Matthew Wild <mwild1@gmail.com>
	Sat, 24 Sep 2022 09:25:46 +0100
changeset 5062	39c2824c2880
parent 4316	33a41503b9e3
permissions	-rw-r--r--