developer_api.rst 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678
  1. The converse.js developer API
  2. =============================
  3. .. note:: The API documented here is available in Converse.js 0.8.4 and higher.
  4. Earlier versions of Converse.js might have different API methods or none at all.
  5. In the Converse.js API, you traverse towards a logical grouping, from
  6. which you can then call certain standardised accessors and mutators, such as::
  7. .get
  8. .set
  9. .add
  10. .remove
  11. This is done to increase readability and to allow intuitive method chaining.
  12. For example, to get a contact, you would do the following::
  13. converse.contacts.get('jid@example.com');
  14. To get multiple contacts, just pass in an array of jids::
  15. converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
  16. To get all contacts, simply call ``get`` without any jids::
  17. converse.contacts.get();
  18. **Here follows now a breakdown of all API groupings and methods**:
  19. initialize
  20. ----------
  21. .. note:: This method is the one exception of a method which is not logically grouped
  22. as explained above.
  23. Initializes converse.js. This method must always be called when using
  24. converse.js.
  25. The `initialize` method takes a map (also called a hash or dictionary) of :ref:`configuration-variables`.
  26. Example:
  27. .. code-block:: javascript
  28. converse.initialize({
  29. allow_otr: true,
  30. auto_list_rooms: false,
  31. auto_subscribe: false,
  32. bosh_service_url: 'https://bind.example.com',
  33. hide_muc_server: false,
  34. i18n: locales['en'],
  35. keepalive: true,
  36. play_sounds: true,
  37. prebind: false,
  38. show_controlbox_by_default: true,
  39. debug: false,
  40. roster_groups: true
  41. });
  42. send
  43. ----
  44. Allows you to send XML stanzas.
  45. For example, to send a message stanza:
  46. .. code-block:: javascript
  47. var msg = converse.env.$msg({
  48. from: 'juliet@example.com/balcony',
  49. to:'romeo@example.net',
  50. type:'chat'
  51. });
  52. converse.send(msg);
  53. The "archive" grouping
  54. ----------------------
  55. Converse.js supports the *Message Archive Management*
  56. (`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
  57. through which it is able to query an XMPP server for archived messages.
  58. See also the **message_archiving** option in the :ref:`configuration-variables` section, which you'll usually
  59. want to in conjunction with this API.
  60. query
  61. ~~~~~
  62. The ``query`` method is used to query for archived messages.
  63. It accepts the following optional parameters:
  64. * **options** an object containing the query parameters. Valid query parameters
  65. are ``with``, ``start``, ``end``, ``first``, ``last``, ``after``, ``before``, ``index`` and ``count``.
  66. * **callback** is the callback method that will be called when all the messages
  67. have been received.
  68. * **errback** is the callback method to be called when an error is returned by
  69. the XMPP server, for example when it doesn't support message archiving.
  70. Examples
  71. ^^^^^^^^
  72. **Requesting all archived messages**
  73. The simplest query that can be made is to simply not pass in any parameters.
  74. Such a query will return all archived messages for the current user.
  75. Generally, you'll however always want to pass in a callback method, to receive
  76. the returned messages.
  77. .. code-block:: javascript
  78. var errback = function (iq) {
  79. // The query was not successful, perhaps inform the user?
  80. // The IQ stanza returned by the XMPP server is passed in, so that you
  81. // may inspect it and determine what the problem was.
  82. }
  83. var callback = function (messages) {
  84. // Do something with the messages, like showing them in your webpage.
  85. }
  86. converse.archive.query(callback, errback))
  87. **Waiting until server support has been determined**
  88. The query method will only work if converse.js has been able to determine that
  89. the server supports MAM queries, otherwise the following error will be raised:
  90. - *This server does not support XEP-0313, Message Archive Management*
  91. The very first time converse.js loads in a browser tab, if you call the query
  92. API too quickly, the above error might appear because service discovery has not
  93. yet been completed.
  94. To work solve this problem, you can first listen for the ``serviceDiscovered`` event,
  95. through which you can be informed once support for MAM has been determined.
  96. For example:
  97. .. code-block:: javascript
  98. converse.listen.on('serviceDiscovered', function (event, feature) {
  99. if (feature.get('var') === converse.env.Strophe.NS.MAM) {
  100. converse.archive.query()
  101. }
  102. });
  103. **Requesting all archived messages for a particular contact or room**
  104. To query for messages sent between the current user and another user or room,
  105. the query options need to contain the the JID (Jabber ID) of the user or
  106. room under the ``with`` key.
  107. .. code-block:: javascript
  108. // For a particular user
  109. converse.archive.query({'with': 'john@doe.net'}, callback, errback);)
  110. // For a particular room
  111. converse.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
  112. **Requesting all archived messages before or after a certain date**
  113. The ``start`` and ``end`` parameters are used to query for messages
  114. within a certain timeframe. The passed in date values may either be ISO8601
  115. formatted date strings, or Javascript Date objects.
  116. .. code-block:: javascript
  117. var options = {
  118. 'with': 'john@doe.net',
  119. 'start': '2010-06-07T00:00:00Z',
  120. 'end': '2010-07-07T13:23:54Z'
  121. };
  122. converse.archive.query(options, callback, errback);
  123. **Limiting the amount of messages returned**
  124. The amount of returned messages may be limited with the ``max`` parameter.
  125. By default, the messages are returned from oldest to newest.
  126. .. code-block:: javascript
  127. // Return maximum 10 archived messages
  128. converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
  129. **Paging forwards through a set of archived messages**
  130. When limiting the amount of messages returned per query, you might want to
  131. repeatedly make a further query to fetch the next batch of messages.
  132. To simplify this usecase for you, the callback method receives not only an array
  133. with the returned archived messages, but also a special RSM (*Result Set
  134. Management*) object which contains the query parameters you passed in, as well
  135. as two utility methods ``next``, and ``previous``.
  136. When you call one of these utility methods on the returned RSM object, and then
  137. pass the result into a new query, you'll receive the next or previous batch of
  138. archived messages. Please note, when calling these methods, pass in an integer
  139. to limit your results.
  140. .. code-block:: javascript
  141. var callback = function (messages, rsm) {
  142. // Do something with the messages, like showing them in your webpage.
  143. // ...
  144. // You can now use the returned "rsm" object, to fetch the next batch of messages:
  145. converse.archive.query(rsm.next(10), callback, errback))
  146. }
  147. converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
  148. **Paging backwards through a set of archived messages**
  149. To page backwards through the archive, you need to know the UID of the message
  150. which you'd like to page backwards from and then pass that as value for the
  151. ``before`` parameter. If you simply want to page backwards from the most recent
  152. message, pass in the ``before`` parameter with an empty string value ``''``.
  153. .. code-block:: javascript
  154. converse.archive.query({'before': '', 'max':5}, function (message, rsm) {
  155. // Do something with the messages, like showing them in your webpage.
  156. // ...
  157. // You can now use the returned "rsm" object, to fetch the previous batch of messages:
  158. rsm.previous(5); // Call previous method, to update the object's parameters,
  159. // passing in a limit value of 5.
  160. // Now we query again, to get the previous batch.
  161. converse.archive.query(rsm, callback, errback);
  162. }
  163. The "connection" grouping
  164. -------------------------
  165. This grouping collects API functions related to the XMPP connection.
  166. connected
  167. ~~~~~~~~~
  168. A boolean attribute (i.e. not a callable) which is set to `true` or `false` depending
  169. on whether there is an established connection.
  170. disconnect
  171. ~~~~~~~~~~
  172. Terminates the connection.
  173. The "user" grouping
  174. -------------------
  175. This grouping collects API functions related to the current logged in user.
  176. jid
  177. ~~~
  178. Return's the current user's full JID (Jabber ID).
  179. .. code-block:: javascript
  180. converse.user.jid()
  181. // Returns for example jc@opkode.com/conversejs-351236
  182. login
  183. ~~~~~
  184. Logs the user in. This method can accept a map with the credentials, like this:
  185. .. code-block:: javascript
  186. converse.user.login({
  187. 'jid': 'dummy@example.com',
  188. 'password': 'secret'
  189. });
  190. or it can be called without any parameters, in which case converse.js will try
  191. to log the user in by calling the `prebind_url` or `credentials_url` depending
  192. on whether prebinding is used or not.
  193. logout
  194. ~~~~~~
  195. Log the user out of the current XMPP session.
  196. .. code-block:: javascript
  197. converse.user.logout();
  198. The "status" sub-grouping
  199. ~~~~~~~~~~~~~~~~~~~~~~~~~
  200. Set and get the user's chat status, also called their *availability*.
  201. get
  202. ^^^
  203. Return the current user's availability status:
  204. .. code-block:: javascript
  205. converse.user.status.get(); // Returns for example "dnd"
  206. set
  207. ^^^
  208. The user's status can be set to one of the following values:
  209. * **away**
  210. * **dnd**
  211. * **offline**
  212. * **online**
  213. * **unavailable**
  214. * **xa**
  215. For example:
  216. .. code-block:: javascript
  217. converse.user.status.set('dnd');
  218. Because the user's availability is often set together with a custom status
  219. message, this method also allows you to pass in a status message as a
  220. second parameter:
  221. .. code-block:: javascript
  222. converse.user.status.set('dnd', 'In a meeting');
  223. The "message" sub-grouping
  224. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  225. The ``user.status.message`` sub-grouping exposes methods for setting and
  226. retrieving the user's custom status message.
  227. .. code-block:: javascript
  228. converse.user.status.message.set('In a meeting');
  229. converse.user.status.message.get(); // Returns "In a meeting"
  230. The "contacts" grouping
  231. -----------------------
  232. get
  233. ~~~
  234. This method is used to retrieve roster contacts.
  235. To get a single roster contact, call the method with the contact's JID (Jabber ID):
  236. .. code-block:: javascript
  237. converse.contacts.get('buddy@example.com')
  238. To get multiple contacts, pass in an array of JIDs:
  239. .. code-block:: javascript
  240. converse.contacts.get(['buddy1@example.com', 'buddy2@example.com'])
  241. To return all contacts, simply call ``get`` without any parameters:
  242. .. code-block:: javascript
  243. converse.contacts.get()
  244. The returned roster contact objects have these attributes:
  245. +----------------+-----------------------------------------------------------------------------------------------------------------+
  246. | Attribute | |
  247. +================+=================================================================================================================+
  248. | ask | If ask === 'subscribe', then we have asked this person to be our chat buddy. |
  249. +----------------+-----------------------------------------------------------------------------------------------------------------+
  250. | fullname | The person's full name. |
  251. +----------------+-----------------------------------------------------------------------------------------------------------------+
  252. | jid | The person's Jabber/XMPP username. |
  253. +----------------+-----------------------------------------------------------------------------------------------------------------+
  254. | requesting | If true, then this person is asking to be our chat buddy. |
  255. +----------------+-----------------------------------------------------------------------------------------------------------------+
  256. | subscription | The subscription state between the current user and this chat buddy. Can be `none`, `to`, `from` or `both`. |
  257. +----------------+-----------------------------------------------------------------------------------------------------------------+
  258. | id | A unique id, same as the jid. |
  259. +----------------+-----------------------------------------------------------------------------------------------------------------+
  260. | chat_status | The person's chat status. Can be `online`, `offline`, `busy`, `xa` (extended away) or `away`. |
  261. +----------------+-----------------------------------------------------------------------------------------------------------------+
  262. | user_id | The user id part of the JID (the part before the `@`). |
  263. +----------------+-----------------------------------------------------------------------------------------------------------------+
  264. | resources | The known resources for this chat buddy. Each resource denotes a separate and connected chat client. |
  265. +----------------+-----------------------------------------------------------------------------------------------------------------+
  266. | groups | The roster groups in which this chat buddy was placed. |
  267. +----------------+-----------------------------------------------------------------------------------------------------------------+
  268. | status | Their human readable custom status message. |
  269. +----------------+-----------------------------------------------------------------------------------------------------------------+
  270. | image_type | The image's file type. |
  271. +----------------+-----------------------------------------------------------------------------------------------------------------+
  272. | image | The Base64 encoded image data. |
  273. +----------------+-----------------------------------------------------------------------------------------------------------------+
  274. | url | The buddy's website URL, as specified in their VCard data. |
  275. +----------------+-----------------------------------------------------------------------------------------------------------------+
  276. | vcard_updated | When last the buddy's VCard was updated. |
  277. +----------------+-----------------------------------------------------------------------------------------------------------------+
  278. add
  279. ~~~
  280. Add a contact.
  281. Provide the JID of the contact you want to add:
  282. .. code-block:: javascript
  283. converse.contacts.add('buddy@example.com')
  284. You may also provide the fullname. If not present, we use the jid as fullname:
  285. .. code-block:: javascript
  286. converse.contacts.add('buddy@example.com', 'Buddy')
  287. The "chats" grouping
  288. --------------------
  289. Note, for MUC chat rooms, you need to use the "rooms" grouping instead.
  290. get
  291. ~~~
  292. Returns an object representing a chat box.
  293. To return a single chat box, provide the JID of the contact you're chatting
  294. with in that chat box:
  295. .. code-block:: javascript
  296. converse.chats.get('buddy@example.com')
  297. To return an array of chat boxes, provide an array of JIDs:
  298. .. code-block:: javascript
  299. converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
  300. To return all open chat boxes, call the method without any JIDs::
  301. converse.chats.get()
  302. open
  303. ~~~~
  304. Opens a chat box and returns an object representing a chat box.
  305. To open a single chat box, provide the JID of the contact:
  306. .. code-block:: javascript
  307. converse.chats.open('buddy@example.com')
  308. To return an array of chat boxes, provide an array of JIDs:
  309. .. code-block:: javascript
  310. converse.chats.open(['buddy1@example.com', 'buddy2@example.com'])
  311. *The returned chat box object contains the following methods:*
  312. +-------------+------------------------------------------+
  313. | Method | Description |
  314. +=============+==========================================+
  315. | endOTR | End an OTR (Off-the-record) session. |
  316. +-------------+------------------------------------------+
  317. | get | Get an attribute (i.e. accessor). |
  318. +-------------+------------------------------------------+
  319. | initiateOTR | Start an OTR (off-the-record) session. |
  320. +-------------+------------------------------------------+
  321. | maximize | Minimize the chat box. |
  322. +-------------+------------------------------------------+
  323. | minimize | Maximize the chat box. |
  324. +-------------+------------------------------------------+
  325. | set | Set an attribute (i.e. mutator). |
  326. +-------------+------------------------------------------+
  327. | close | Close the chat box. |
  328. +-------------+------------------------------------------+
  329. | open | Opens the chat box. |
  330. +-------------+------------------------------------------+
  331. *The get and set methods can be used to retrieve and change the following attributes:*
  332. +-------------+-----------------------------------------------------+
  333. | Attribute | Description |
  334. +=============+=====================================================+
  335. | height | The height of the chat box. |
  336. +-------------+-----------------------------------------------------+
  337. | url | The URL of the chat box heading. |
  338. +-------------+-----------------------------------------------------+
  339. The "rooms" grouping
  340. --------------------
  341. get
  342. ~~~
  343. Returns an object representing a multi user chat box (room).
  344. It takes 3 parameters:
  345. * the room JID (if not specified, all rooms will be returned).
  346. * a map (object) containing any extra room attributes For example, if you want
  347. to specify the nickname, use ``{'nick': 'bloodninja'}``. Previously (before
  348. version 1.0.7, the second parameter only accepted the nickname (as a string
  349. value). This is currently still accepted, but then you can't pass in any
  350. other room attributes. If the nickname is not specified then the node part of
  351. the user's JID will be used.
  352. * a boolean, indicating whether the room should be created if not found (default: `false`)
  353. .. code-block:: javascript
  354. var nick = 'dread-pirate-roberts';
  355. var create_if_not_found = true;
  356. converse.rooms.open('group@muc.example.com', {'nick': nick}, create_if_not_found)
  357. open
  358. ~~~~
  359. Opens a multi user chat box and returns an object representing it.
  360. Similar to chats.get API
  361. It takes 2 parameters:
  362. * the room JID (if not specified, all rooms will be returned).
  363. * a map (object) containing any extra room attributes. For example, if you want
  364. to specify the nickname, use ``{'nick': 'bloodninja'}``.
  365. To open a single multi user chat box, provide the JID of the room:
  366. .. code-block:: javascript
  367. converse.rooms.open('group@muc.example.com')
  368. To return an array of rooms, provide an array of room JIDs:
  369. .. code-block:: javascript
  370. converse.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
  371. To setup a custom nickname when joining the room, provide the optional nick argument:
  372. .. code-block:: javascript
  373. converse.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
  374. close
  375. ~~~~~
  376. Lets you close open chat rooms. You can call this method without any arguments
  377. to close all open chat rooms, or you can specify a single JID or an array of
  378. JIDs.
  379. The "settings" grouping
  380. -----------------------
  381. This grouping allows you to get or set the configuration settings of converse.js.
  382. get(key)
  383. ~~~~~~~~
  384. Returns the value of a configuration settings. For example:
  385. .. code-block:: javascript
  386. converse.settings.get("play_sounds"); // default value returned would be false;
  387. set(key, value) or set(object)
  388. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  389. Set one or many configuration settings. For example:
  390. .. code-block:: javascript
  391. converse.settings.set("play_sounds", true);
  392. or :
  393. .. code-block:: javascript
  394. converse.settings.set({
  395. "play_sounds", true,
  396. "hide_offline_users" true
  397. });
  398. Note, this is not an alternative to calling ``converse.initialize``, which still needs
  399. to be called. Generally, you'd use this method after converse.js is already
  400. running and you want to change the configuration on-the-fly.
  401. The "tokens" grouping
  402. ---------------------
  403. get
  404. ~~~
  405. Returns a token, either the RID or SID token depending on what's asked for.
  406. Example:
  407. .. code-block:: javascript
  408. converse.tokens.get('rid')
  409. .. _`listen-grouping`:
  410. The "listen" grouping
  411. ---------------------
  412. Converse.js emits events to which you can subscribe from your own Javascript.
  413. Concerning events, the following methods are available under the "listen"
  414. grouping:
  415. * **on(eventName, callback, [context])**:
  416. Calling the ``on`` method allows you to subscribe to an event.
  417. Every time the event fires, the callback method specified by ``callback`` will be
  418. called.
  419. Parameters:
  420. * ``eventName`` is the event name as a string.
  421. * ``callback`` is the callback method to be called when the event is emitted.
  422. * ``context`` (optional), the value of the `this` parameter for the callback.
  423. For example:
  424. .. code-block:: javascript
  425. converse.listen.on('message', function (event, messageXML) { ... });
  426. * **once(eventName, callback, [context])**:
  427. Calling the ``once`` method allows you to listen to an event
  428. exactly once.
  429. Parameters:
  430. * ``eventName`` is the event name as a string.
  431. * ``callback`` is the callback method to be called when the event is emitted.
  432. * ``context`` (optional), the value of the `this` parameter for the callback.
  433. For example:
  434. .. code-block:: javascript
  435. converse.listen.once('message', function (event, messageXML) { ... });
  436. * **not(eventName, callback)**
  437. To stop listening to an event, you can use the ``not`` method.
  438. Parameters:
  439. * ``eventName`` is the event name as a string.
  440. * ``callback`` refers to the function that is to be no longer executed.
  441. For example:
  442. .. code-block:: javascript
  443. converse.listen.not('message', function (event, messageXML) { ... });