Converse converse.js

API Documentation

Namespace: api

_converse.api

The private API

The private API methods are only accessible via the closured _converse object, which is only available to plugins.

These methods are kept private (i.e. not global) because they may return sensitive data which should be kept off-limits to other 3rd-party scripts that might be running in the page.

Source:

Namespaces

archive
archive
connection
connection
contacts
contacts
controlbox
listen
listen
modal
omemo
promises
promises
pubsub
pubsub
settings
settings
user
user
vcard
vcard

Methods

(static) alert(type, title, messages)

Show an alert modal to the user.

Parameters:
Name Type Description
type 'info' | 'warn' | 'error'

The type of alert.
title String

The header text for the alert.
messages Array.<String> | String

The alert text to show to the user.
Source:

(static) confirm(title, messages, fields) → {Promise.<(Array|false)>}

Show a confirm modal to the user.

Parameters:
Name Type Description
title String

The header text for the confirmation dialog
messages Array.<String> | String

The text to show to the user
fields Array.<Field>

An object representing a fields presented to the user.
Properties:
Name Type Attributes Description
Field.label String

The form label for the input field.
Field.name String

The name for the input field.
Field.challenge String <optional>

A challenge value that must be provided by the user.
Field.placeholder String <optional>

The placeholder for the input field.
Field.required Boolean <optional>

Whether the field is required or not
Source:
Returns:

A promise which resolves with an array of filled in fields or false if the confirm dialog was closed or canceled.

Type
Promise.<(Array|false)>

(static) prompt(title, messages, placeholder) → {Promise.<(String|false)>}

Show a prompt modal to the user.

Parameters:
Name Type Description
title String

The header text for the prompt
messages Array.<String> | String

The prompt text to show to the user
placeholder String

The placeholder text for the prompt input
Source:
Returns:

A promise which resolves with the text provided by the user or false if the user canceled the prompt.

Type
Promise.<(String|false)>

(static) send(stanza) → {void}

Allows you to send XML stanzas.

Parameters:
Name Type Description
stanza Element | Stanza
Source:
Returns:
Type
void
Example
const msg = converse.env.$msg({
    'from': 'juliet@example.com/balcony',
    'to': 'romeo@example.net',
    'type':'chat'
});
_converse.api.send(msg);

(static) send(stanza) → {void}

Allows you to send XML stanzas.

Parameters:
Name Type Description
stanza Element | Stanza
Source:
Returns:
Type
void
Example
const msg = converse.env.$msg({
    'from': 'juliet@example.com/balcony',
    'to': 'romeo@example.net',
    'type':'chat'
});
_converse.api.send(msg);

(static) sendIQ(stanza, timeoutopt, rejectopt) → {Promise}

Send an IQ stanza

Parameters:
Name Type Attributes Default Description
stanza Element
timeout number <optional>

The default timeout value is taken from the stanza_timeout configuration setting.
reject Boolean <optional>
 true

Whether an error IQ should cause the promise to be rejected. If false, the promise will resolve instead of being rejected.
Source:
Returns:

A promise which resolves (or potentially rejected) once we receive a result or error stanza or once a timeout is reached. If the IQ stanza being sent is of type result or error, there's nothing to wait for, so an already resolved promise is returned.

Type
Promise

(static) sendIQ(stanza, timeoutopt, rejectopt) → {Promise}

Send an IQ stanza

Parameters:
Name Type Attributes Default Description
stanza Element
timeout number <optional>

The default timeout value is taken from the stanza_timeout configuration setting.
reject Boolean <optional>
 true

Whether an error IQ should cause the promise to be rejected. If false, the promise will resolve instead of being rejected.
Source:
Returns:

A promise which resolves (or potentially rejected) once we receive a result or error stanza or once a timeout is reached. If the IQ stanza being sent is of type result or error, there's nothing to wait for, so an already resolved promise is returned.

Type
Promise

(static) trigger(name, …argumentopt, optionsopt)

Lets you trigger events, which can be listened to via _converse.api.listen.on or _converse.api.listen.once (see _converse.api.listen).

Some events also double as promises and can be waited on via _converse.api.waitUntil.

Parameters:
Name Type Attributes Description
name string

The event name
argument any <optional>
<repeatable>

Argument to be passed to the event handler
options object <optional>
Properties
Name Type Attributes Description
synchronous boolean <optional>

Whether the event is synchronous or not. When a synchronous event is fired, a promise will be returned by _converse.api.trigger which resolves once all the event handlers' promises have been resolved.
Source:

(static) trigger(name, …argumentopt, optionsopt)

Lets you trigger events, which can be listened to via _converse.api.listen.on or _converse.api.listen.once (see _converse.api.listen).

Some events also double as promises and can be waited on via _converse.api.waitUntil.

Parameters:
Name Type Attributes Description
name string

The event name
argument any <optional>
<repeatable>

Argument to be passed to the event handler
options object <optional>
Properties
Name Type Attributes Description
synchronous boolean <optional>

Whether the event is synchronous or not. When a synchronous event is fired, a promise will be returned by _converse.api.trigger which resolves once all the event handlers' promises have been resolved.
Source:

(static) waitUntil(condition) → {Promise}

Wait until a promise is resolved or until the passed in function returns a truthy value.

Parameters:
Name Type Description
condition string | function

The name of the promise to wait for, or a function which should eventually return a truthy value.
Source:
Returns:
Type
Promise

(static) waitUntil(condition) → {Promise}

Wait until a promise is resolved or until the passed in function returns a truthy value.

Parameters:
Name Type Description
condition string | function

The name of the promise to wait for, or a function which should eventually return a truthy value.
Source:
Returns:
Type
Promise

_converse.api

The private API

The private API methods are only accessible via the closured _converse object, which is only available to plugins.

These methods are kept private (i.e. not global) because they may return sensitive data which should be kept off-limits to other 3rd-party scripts that might be running in the page.

Source:

Namespaces

archive
archive
connection
connection
contacts
contacts
controlbox
listen
listen
modal
omemo
promises
promises
pubsub
pubsub
settings
settings
user
user
vcard
vcard

Methods

(static) alert(type, title, messages)

Show an alert modal to the user.

Parameters:
Name Type Description
type 'info' | 'warn' | 'error'

The type of alert.
title String

The header text for the alert.
messages Array.<String> | String

The alert text to show to the user.
Source:

(static) confirm(title, messages, fields) → {Promise.<(Array|false)>}

Show a confirm modal to the user.

Parameters:
Name Type Description
title String

The header text for the confirmation dialog
messages Array.<String> | String

The text to show to the user
fields Array.<Field>

An object representing a fields presented to the user.
Properties:
Name Type Attributes Description
Field.label String

The form label for the input field.
Field.name String

The name for the input field.
Field.challenge String <optional>

A challenge value that must be provided by the user.
Field.placeholder String <optional>

The placeholder for the input field.
Field.required Boolean <optional>

Whether the field is required or not
Source:
Returns:

A promise which resolves with an array of filled in fields or false if the confirm dialog was closed or canceled.

Type
Promise.<(Array|false)>

(static) prompt(title, messages, placeholder) → {Promise.<(String|false)>}

Show a prompt modal to the user.

Parameters:
Name Type Description
title String

The header text for the prompt
messages Array.<String> | String

The prompt text to show to the user
placeholder String

The placeholder text for the prompt input
Source:
Returns:

A promise which resolves with the text provided by the user or false if the user canceled the prompt.

Type
Promise.<(String|false)>

(static) send(stanza) → {void}

Allows you to send XML stanzas.

Parameters:
Name Type Description
stanza Element | Stanza
Source:
Returns:
Type
void
Example
const msg = converse.env.$msg({
    'from': 'juliet@example.com/balcony',
    'to': 'romeo@example.net',
    'type':'chat'
});
_converse.api.send(msg);

(static) send(stanza) → {void}

Allows you to send XML stanzas.

Parameters:
Name Type Description
stanza Element | Stanza
Source:
Returns:
Type
void
Example
const msg = converse.env.$msg({
    'from': 'juliet@example.com/balcony',
    'to': 'romeo@example.net',
    'type':'chat'
});
_converse.api.send(msg);

(static) sendIQ(stanza, timeoutopt, rejectopt) → {Promise}

Send an IQ stanza

Parameters:
Name Type Attributes Default Description
stanza Element
timeout number <optional>

The default timeout value is taken from the stanza_timeout configuration setting.
reject Boolean <optional>
 true

Whether an error IQ should cause the promise to be rejected. If false, the promise will resolve instead of being rejected.
Source:
Returns:

A promise which resolves (or potentially rejected) once we receive a result or error stanza or once a timeout is reached. If the IQ stanza being sent is of type result or error, there's nothing to wait for, so an already resolved promise is returned.

Type
Promise

(static) sendIQ(stanza, timeoutopt, rejectopt) → {Promise}

Send an IQ stanza

Parameters:
Name Type Attributes Default Description
stanza Element
timeout number <optional>

The default timeout value is taken from the stanza_timeout configuration setting.
reject Boolean <optional>
 true

Whether an error IQ should cause the promise to be rejected. If false, the promise will resolve instead of being rejected.
Source:
Returns:

A promise which resolves (or potentially rejected) once we receive a result or error stanza or once a timeout is reached. If the IQ stanza being sent is of type result or error, there's nothing to wait for, so an already resolved promise is returned.

Type
Promise

(static) trigger(name, …argumentopt, optionsopt)

Lets you trigger events, which can be listened to via _converse.api.listen.on or _converse.api.listen.once (see _converse.api.listen).

Some events also double as promises and can be waited on via _converse.api.waitUntil.

Parameters:
Name Type Attributes Description
name string

The event name
argument any <optional>
<repeatable>

Argument to be passed to the event handler
options object <optional>
Properties
Name Type Attributes Description
synchronous boolean <optional>

Whether the event is synchronous or not. When a synchronous event is fired, a promise will be returned by _converse.api.trigger which resolves once all the event handlers' promises have been resolved.
Source:

(static) trigger(name, …argumentopt, optionsopt)

Lets you trigger events, which can be listened to via _converse.api.listen.on or _converse.api.listen.once (see _converse.api.listen).

Some events also double as promises and can be waited on via _converse.api.waitUntil.

Parameters:
Name Type Attributes Description
name string

The event name
argument any <optional>
<repeatable>

Argument to be passed to the event handler
options object <optional>
Properties
Name Type Attributes Description
synchronous boolean <optional>

Whether the event is synchronous or not. When a synchronous event is fired, a promise will be returned by _converse.api.trigger which resolves once all the event handlers' promises have been resolved.
Source:

(static) waitUntil(condition) → {Promise}

Wait until a promise is resolved or until the passed in function returns a truthy value.

Parameters:
Name Type Description
condition string | function

The name of the promise to wait for, or a function which should eventually return a truthy value.
Source:
Returns:
Type
Promise

(static) waitUntil(condition) → {Promise}

Wait until a promise is resolved or until the passed in function returns a truthy value.

Parameters:
Name Type Description
condition string | function

The name of the promise to wait for, or a function which should eventually return a truthy value.
Source:
Returns:
Type
Promise