Converse converse.js

API Documentation

Source: headless/plugins/status/api.js

  1. import { _converse, api } from '../../core';
  2. import { STATUS_WEIGHTS } from '../../shared/constants';
  5. export default {
  6.     /**
  7.      * Set and get the user's chat status, also called their *availability*.
  8.      * @namespace _converse.api.user.status
  9.      * @memberOf _converse.api.user
  10.      */
  11.     status: {
  12.         /**
  13.          * Return the current user's availability status.
  14.          * @async
  15.          * @method _converse.api.user.status.get
  16.          * @example _converse.api.user.status.get();
  17.          */
  18.         async get () {
  19.             await api.waitUntil('statusInitialized');
  20.             return _converse.xmppstatus.get('status');
  21.         },
  23.         /**
  24.          * The user's status can be set to one of the following values:
  25.          *
  26.          * @async
  27.          * @method _converse.api.user.status.set
  28.          * @param { string } value The user's chat status (e.g. 'away', 'dnd', 'offline', 'online', 'unavailable' or 'xa')
  29.          * @param { string } [message] A custom status message
  30.          *
  31.          * @example _converse.api.user.status.set('dnd');
  32.          * @example _converse.api.user.status.set('dnd', 'In a meeting');
  33.          */
  34.         async set (value, message) {
  35.             const data = {'status': value};
  36.             if (!Object.keys(STATUS_WEIGHTS).includes(value)) {
  37.                 throw new Error(
  38.                     'Invalid availability value. See https://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2.1'
  39.                 );
  40.             }
  41.             if (typeof message === 'string') {
  42.                 data.status_message = message;
  43.             }
  44.             await api.waitUntil('statusInitialized');
  45.             _converse.xmppstatus.save(data);
  46.         },
  48.         /**
  49.          * Set and retrieve the user's custom status message.
  50.          *
  51.          * @namespace _converse.api.user.status.message
  52.          * @memberOf _converse.api.user.status
  53.          */
  54.         message: {
  55.             /**
  56.              * @async
  57.              * @method _converse.api.user.status.message.get
  58.              * @returns { Promise<string> } The status message
  59.              * @example const message = _converse.api.user.status.message.get()
  60.              */
  61.             async get () {
  62.                 await api.waitUntil('statusInitialized');
  63.                 return _converse.xmppstatus.get('status_message');
  64.             },
  65.             /**
  66.              * @async
  67.              * @method _converse.api.user.status.message.set
  68.              * @param { string } status The status message
  69.              * @example _converse.api.user.status.message.set('In a meeting');
  70.              */
  71.             async set (status) {
  72.                 await api.waitUntil('statusInitialized');
  73.                 _converse.xmppstatus.save({ status_message: status });
  74.             }
  75.         }
  76.     }
  77. }