mod_groups_internal

Introduction

This module is functionally similar to mod_groups, but it differs by working without a configuration file (allowing changes without a restart of the server) and by permanently adding users to each other’s contact lists. To paraphrase mod_groups:

mod_groups_internal was designed to allow administrators to create virtual groups of users that automatically see each other in their contact lists. There is no need for the user to authorise these contacts in their contact list - this is done automatically on the server.

As an example, if you have a team of people working together on a project, you can create a group for that team. They will automatically be added to each others’ contact lists, and the list can easily be modified on the server at any time to add and remove people.

Setup

modules_enabled = {
    -- Other modules
    "groups_internal"; -- Enable mod_groups_internal
}

Configuration

Usage

Exposed functions

• create(group_info, create_default_muc, group_id)

  Creates a new group, optionally creating a default MUC chat on groups_muc_host.

  Parameters:

  1. group_info: { name: string }
  2. create_default_muc: boolean | nil: Whether or not to create the default MUC chat. Defaults to false.
  3. group_id: string | nil: The desired group JID node part. Defaults to util.id.short (9-chars URL-safe base64).

  Returns: group_id: string | nil, error: string

• get_info(group_id)

  Retrieves information about a group.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns:

  group_info: {
    name: string,
    muc_jid: string | nil
  }
  | nil

• set_info(group_id, info)

  Allows one to change a group’s name. If muc_jid is specified, this function will also update the group chat’s name.

  Parameters:

  1. group_id: string: Node part of the group’s JID.
  2. group_info: { name: string, muc_jid: string | nil }

  Returns: true | nil, error: string

• get_members(group_id)

  Retrieves the list of members in a given group.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns: group_members: {string}

• exists(group_id)

  Returns whether or not a group exists.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns: group_exists: boolean

• get_user_groups(username)

  Lists which groups a given user is a part of.

  Parameters:

  1. username: string: Node part of the user’s JID.

  Returns: user_groups: {string}

• delete(group_id)

  Deletes a given group and its associated group chats.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns: true | nil, error: string

• add_member(group_id, username, delay_update)

  Adds a member to a given group, optionally delaying subscriptions until sync is called.

  This function emits a group-user-added event on successful execution.

  Parameters:

  1. group_id: string: Node part of the group’s JID.
  2. delay_update: boolean | nil: Do not update subscriptions until sync is called. Defaults to false.

  Returns: true | nil, error: string

• remove_member(group_id, username)

  Removes a member from a given group.

  This function emits a group-user-removed event on successful execution.

  Parameters:

  1. group_id: string: Node part of the group’s JID.
  2. username: string: Node part of the user’s JID.

  Returns: true | nil, error: string

• sync(group_id)

  Updates group subscriptions (used to apply pending changes from add_member).

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns: nil

• add_group_chat(group_id, name)

  Creates a new group chat for a given group.

  Its JID will be <util.id.short>@<option:groups_muc_host>.

  Parameters:

  1. group_id: string: Node part of the group’s JID.
  2. name: string: Desired name of the group chat.

  Returns:

  muc: {
    jid: string,
    name: string,
  }
  | nil, error: string

• remove_group_chat(group_id, muc_id)

  Removes a group chat for a given group.

  This function emits a group-chat-removed event on successful execution.

  Parameters:

  1. group_id: string: Node part of the group’s JID.
  2. muc_id: string: Node part of the MUC JID.

  Returns: true | nil, error: string

• get_group_chats(group_id)

  Lists group chats associated to a given group.

  Make sure to check the deleted property on each chat as this function might return information about deleted chats.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns:

  group_chats: {
    {
      id: string, -- muc_id (node part of the MUC JID)
      jid: string,
      name: string,
      deleted: boolean,
    }
  }
  | nil

• emit_member_events(group_id)

  Emits group-user-added events for every member of a group.

  Parameters:

  1. group_id: string: Node part of the group’s JID.

  Returns: true | false, error: string

• groups()

  Returns info about all groups (for every group_id key, the value is the equivalent of calling get_info(group_id)).

  Returns:

  groups: {
    <group_id>: {
      name: string,
      muc_jid: string | nil
    }
  }

  (Where <group_id> is a

Emitted events

• group-user-added

  Emitted on successful add_member and on emit_member_events.

  Payload structure:

  {
    id: string, -- group_id (node part of the group's JID)
    user: string, -- username (node part of the user's JID)
    host: string, -- <module.host>
    group_info: {
      name: string,
      muc_jid: string | nil,
      mucs: {string} | nil,
    },
  }

• group-user-removed

  Emitted on successful remove_member.

  Payload structure:

  {
    id: string, -- group_id (node part of the group's JID)
    user: string, -- username (node part of the user's JID)
    host: string, -- <module.host>
    group_info: {
      name: string,
      muc_jid: string | nil,
      mucs: {string} | nil,
    },
  }

• group-chat-added

  Emitted on successful add_group_chat.

  Payload structure:

  {
    group_id: string,
    group_info: {
      name: string,
      mucs: {string},
    },
    muc: {
      jid: string,
      name: string,
    },
  }

• group-chat-removed

  Emitted on successful remove_group_chat.

  Payload structure:

  {
    group_id: string, -- group_id (node part of the group's JID)
    group_info: {
      name: string,
      mucs: {string},
    },
    muc: {
      id: string, -- muc_id (node part of the MUC JID)
      jid: string,
    },
  }

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_groups_internal