The XEP-0313 Message Archive Management API
Enables you to query an XMPP server for archived messages.
See also the message-archiving option in the configuration settings section, which you'll usually want to use in conjunction with this API.
- Source:
Methods
(static) query(options) → {Promise.<module:converse-mam~MAMQueryResult>}
Query for archived messages.
The options parameter can also be an instance of RSM to enable easy querying between results pages.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
module:converse-mam~ArchiveQueryOptions | An object containing query parameters |
- Source:
Throws:
-
An error is thrown if the XMPP server responds with an error.
- Type
- Error
Returns:
A promise which resolves to a module:converse-mam~MAMQueryResult object.
- Type
- Promise.<module:converse-mam~MAMQueryResult>
Examples
// Requesting all archived messages
// ================================
//
// The simplest query that can be made is to simply not pass in any parameters.
// Such a query will return all archived messages for the current user.
let result;
try {
result = await api.archive.query();
} catch (e) {
// The query was not successful, perhaps inform the user?
// The IQ stanza returned by the XMPP server is passed in, so that you
// may inspect it and determine what the problem was.
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));// Requesting all archived messages for a particular contact or room
// =================================================================
//
// To query for messages sent between the current user and another user or room,
// the query options need to contain the the JID (Jabber ID) of the user or
// room under the `with` key.
// For a particular user
let result;
try {
result = await api.archive.query({'with': 'john@doe.net'});
} catch (e) {
// The query was not successful
}
// For a particular room
let result;
try {
result = await api.archive.query({'with': 'discuss@conference.doglovers.net', 'groupchat': true});
} catch (e) {
// The query was not successful
}// Requesting all archived messages before or after a certain date
// ===============================================================
//
// The `start` and `end` parameters are used to query for messages
// within a certain timeframe. The passed in date values may either be ISO8601
// formatted date strings, or JavaScript Date objects.
const options = {
'with': 'john@doe.net',
'start': '2010-06-07T00:00:00Z',
'end': '2010-07-07T13:23:54Z'
};
let result;
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}// Limiting the amount of messages returned
// ========================================
//
// The amount of returned messages may be limited with the `max` parameter.
// By default, the messages are returned from oldest to newest.
// Return maximum 10 archived messages
let result;
try {
result = await api.archive.query({'with': 'john@doe.net', 'max':10});
} catch (e) {
// The query was not successful
}// Paging forwards through a set of archived messages
// ==================================================
//
// When limiting the amount of messages returned per query, you might want to
// repeatedly make a further query to fetch the next batch of messages.
//
// To simplify this usecase for you, the callback method receives not only an array
// with the returned archived messages, but also a special RSM (*Result Set Management*)
// object which contains the query parameters you passed in, as well
// as two utility methods `next`, and `previous`.
//
// When you call one of these utility methods on the returned RSM object, and then
// pass the result into a new query, you'll receive the next or previous batch of
// archived messages. Please note, when calling these methods, pass in an integer
// to limit your results.
const options = {'with': 'john@doe.net', 'max':10};
let result;
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
while (!result.complete) {
try {
result = await api.archive.query(Object.assign(options, rsm.next(10).query));
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
}// Paging backwards through a set of archived messages
// ===================================================
//
// To page backwards through the archive, you need to know the UID of the message
// which you'd like to page backwards from and then pass that as value for the
// `before` parameter. If you simply want to page backwards from the most recent
// message, pass in the `before` parameter with an empty string value `''`.
let result;
const options = {'before': '', 'max':5};
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
// Now we query again, to get the previous batch.
try {
result = await api.archive.query(Object.assign(options, rsm.previous(5).query));
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));(static) query(options) → {Promise.<module:converse-mam~MAMQueryResult>}
Query for archived messages.
The options parameter can also be an instance of RSM to enable easy querying between results pages.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
module:converse-mam~ArchiveQueryOptions | An object containing query parameters |
Throws:
-
An error is thrown if the XMPP server responds with an error.
- Type
- Error
Returns:
A promise which resolves to a module:converse-mam~MAMQueryResult object.
- Type
- Promise.<module:converse-mam~MAMQueryResult>
Examples
// Requesting all archived messages
// ================================
//
// The simplest query that can be made is to simply not pass in any parameters.
// Such a query will return all archived messages for the current user.
let result;
try {
result = await api.archive.query();
} catch (e) {
// The query was not successful, perhaps inform the user?
// The IQ stanza returned by the XMPP server is passed in, so that you
// may inspect it and determine what the problem was.
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));// Requesting all archived messages for a particular contact or room
// =================================================================
//
// To query for messages sent between the current user and another user or room,
// the query options need to contain the the JID (Jabber ID) of the user or
// room under the `with` key.
// For a particular user
let result;
try {
result = await api.archive.query({'with': 'john@doe.net'});
} catch (e) {
// The query was not successful
}
// For a particular room
let result;
try {
result = await api.archive.query({'with': 'discuss@conference.doglovers.net', 'groupchat': true});
} catch (e) {
// The query was not successful
}// Requesting all archived messages before or after a certain date
// ===============================================================
//
// The `start` and `end` parameters are used to query for messages
// within a certain timeframe. The passed in date values may either be ISO8601
// formatted date strings, or JavaScript Date objects.
const options = {
'with': 'john@doe.net',
'start': '2010-06-07T00:00:00Z',
'end': '2010-07-07T13:23:54Z'
};
let result;
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}// Limiting the amount of messages returned
// ========================================
//
// The amount of returned messages may be limited with the `max` parameter.
// By default, the messages are returned from oldest to newest.
// Return maximum 10 archived messages
let result;
try {
result = await api.archive.query({'with': 'john@doe.net', 'max':10});
} catch (e) {
// The query was not successful
}// Paging forwards through a set of archived messages
// ==================================================
//
// When limiting the amount of messages returned per query, you might want to
// repeatedly make a further query to fetch the next batch of messages.
//
// To simplify this usecase for you, the callback method receives not only an array
// with the returned archived messages, but also a special RSM (*Result Set Management*)
// object which contains the query parameters you passed in, as well
// as two utility methods `next`, and `previous`.
//
// When you call one of these utility methods on the returned RSM object, and then
// pass the result into a new query, you'll receive the next or previous batch of
// archived messages. Please note, when calling these methods, pass in an integer
// to limit your results.
const options = {'with': 'john@doe.net', 'max':10};
let result;
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
while (!result.complete) {
try {
result = await api.archive.query(Object.assign(options, rsm.next(10).query));
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
}// Paging backwards through a set of archived messages
// ===================================================
//
// To page backwards through the archive, you need to know the UID of the message
// which you'd like to page backwards from and then pass that as value for the
// `before` parameter. If you simply want to page backwards from the most recent
// message, pass in the `before` parameter with an empty string value `''`.
let result;
const options = {'before': '', 'max':5};
try {
result = await api.archive.query(options);
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));
// Now we query again, to get the previous batch.
try {
result = await api.archive.query(Object.assign(options, rsm.previous(5).query));
} catch (e) {
// The query was not successful
}
// Do something with the messages, like showing them in your webpage.
result.messages.forEach(m => this.showMessage(m));