Converse converse.js

Namespace: archive

_converse.api.archive

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

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));

_converse.api.archive

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

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));