mod_mam Message Archives

This module stores messages in per-user archives, and allows clients that implement XEP-0313 to access the archive.

This can be used to synchronize conversations between multiple clients even if they are offline when the conversation happened, or for clients to display a conversation history browser to the user.

mod_carbons is a related module that is used for synchronization of conversations between online clients.

Usage

Add "mam" to your modules_enabled list:

modules_enabled = {
    -- ...
    "mam",
    -- ...
}

Configuration

Option summary

Option	Default	Description
archive_expires_after	`"1w"`	How long messages are stored in the archive for. See Archive expiry.
default_archive_policy	`true`	Controls whether messages are archived by default. `true` (always), `false` (only if the user enables it), `"roster"` (only for contacts).
archive_cleanup_interval	`46060`	The number of seconds between cleanup tasks (i.e. how often Prosody looks for expired messages and deletes them).
max_archive_query_results	`50`	The maxiumum number of messages returned to a client at a time. Too low will cause excessive queries when clients try to fetch all messages, too high may consume more resources on the server.
archive_store	`"archive"`	The name of the store that messages will be archived in. This should not be changed unless you are upgrading from an earlier version.
dont_archive_namespaces	`{ "http://jabber.org/protocol/chatstates" }`	A list of XMPP namespaces that should not be archived.
mam_smart_enable	`false`	Only enable archiving for users that have queried the archive. This can be used to prevent archiving for users with legacy clients that don’t use it.

Configuring a storage backend

mod_mam uses the store "archive". See Prosodys data storage documentation for information on how to configure storage.

For example, to use mod_storage_sql only for MAM archives:

storage = {
  archive = "sql";
}

If no archive-capable storage backend can be opened then an in-memory one will be used as fallback.

Legacy message archive

Early versions of mod_mam (which were available in prosody-modules) stored data in a store called 'archive2'. This store is now just called 'archive'.

mod_mam can be instructed to use the older store name if you still have data there.

archive_store = "archive2"; -- the old data
storage = {
  archive2 = "sql";
}

Memory-only storage

For performance and privacy reasons, you might prefer to keep messages in memory only. This works best on smaller servers, and obviously if Prosody restarts then it is possible that some clients may not receive messages. Note that if all clients are offline, messages will still be stored via mod_offline.

-- Example to use memory storage for archives, and sql for everything else
default_storage = "sql"
storage = {
    archive = "memory"
}

Message matching policy

The MAM protocol includes a way for clients to control what messages should be stored. This allows users to enable or disable archiving by default or for specific contacts.

The server can specify a default policy using default_archive_policy.

default_archive_policy = true

`default_archive_policy =`	Meaning
`false`	Store no messages.
`"roster"`	Store messages to/from contacts in the users roster.
`true`	Store all messages. This is the default.

If mam_smart_enable is set to true then archiving is disabled until the user either queries their archive or uses the MAM preferences protocol. Once they do, their settings are initialized to the value of default_archive_policy.

Archive expiry

Messages in the archive will expire after some time, by default one week. This can be changed by setting archive_expires_after:

archive_expires_after = "1d" -- one day
 
archive_expires_after = "1w" -- one week, the default
 
archive_expires_after = "2m" -- two months
 
archive_expires_after = "1y" -- one year
 
archive_expires_after = 60 * 60 -- one hour
 
archive_expires_after = "never" -- keep messages forever

The format is an integer number of seconds or a multiple of a period given by a suffix that can be one of d (day), w (week), m (month) or y (year). No multiplier means seconds.

Query size limits

max_archive_query_results = 20

This is the largest number of messages that are allowed to be retrieved in one request page. A query that does not fit in one page will include a reference to the next page, letting clients page through the result set. Setting large number is not recommended, as Prosody will be blocked while processing the request and will not be able to do anything else.