2018-09-02 10:11:37 +02:00
|
|
|
# The Converse API documentation
|
|
|
|
|
|
|
|
## The public and private API
|
|
|
|
|
|
|
|
Converse has a public API and a private API.
|
|
|
|
|
|
|
|
The reason we make this distinction between public and private is so that API
|
|
|
|
methods which might can be used to "impersonate" the user, for example by
|
|
|
|
sending messages on their behalf, are not available to random scripts running
|
|
|
|
in the websites.
|
|
|
|
|
|
|
|
The public API is accessible via the `window.converse` global and is therefore
|
|
|
|
available to all JavaScript running in the page.
|
|
|
|
|
|
|
|
The private API is only accessible to plugins, which have been whitelisted and
|
|
|
|
registered before `converse.initialize` (which is a public API method) has been
|
|
|
|
called. See the [plugin development](https://conversejs.org/docs/html/plugin_development.html)
|
|
|
|
section for more info on writing plugins.
|
|
|
|
|
|
|
|
Inside a plugin, you can get access to the `_converse.api` object. Note the
|
|
|
|
underscore in front of `_converse`, which indicates that this is a private,
|
|
|
|
closured object.
|
|
|
|
|
2018-09-02 12:15:26 +02:00
|
|
|
## API Namespaces
|
2018-09-02 10:11:37 +02:00
|
|
|
|
2018-09-02 12:15:26 +02:00
|
|
|
The Converse API is often broken up into different logical "namespaces" (for
|
2018-09-02 10:11:37 +02:00
|
|
|
example `converse.plugins` or `converse.contacts`).
|
|
|
|
|
|
|
|
There are some exceptions to this, like `converse.initialize`, which aren't
|
2018-09-02 12:15:26 +02:00
|
|
|
namespaces but single methods.
|
2018-09-02 10:11:37 +02:00
|
|
|
|
2018-09-02 12:15:26 +02:00
|
|
|
The namespaces logically group methods, such as standardised accessors and
|
2018-09-02 10:11:37 +02:00
|
|
|
mutators:
|
|
|
|
|
|
|
|
* .get
|
|
|
|
* .set
|
|
|
|
* .add
|
|
|
|
* .remove
|
|
|
|
|
|
|
|
So for example, to get a contact, you would do the following:
|
|
|
|
|
|
|
|
_converse.api.contacts.get('jid@example.com');
|
|
|
|
|
|
|
|
To get multiple contacts, just pass in an array of jids:
|
|
|
|
|
|
|
|
_converse.api.contacts.get(['jid1@example.com', 'jid2@example.com']);
|
|
|
|
|
|
|
|
To get all contacts, simply call ``get`` without any jids:
|
|
|
|
|
|
|
|
_converse.api.contacts.get();
|
|
|
|
|