Introduction

 

Developer Preview
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.

 

Note: This module is universal. Functions in this module can run on both the backend and frontend, unless specified otherwise.

The Groups API provides functionality for managing groups, including creating, deleting, updating, and querying groups.

Settings for Typical Use Case

Site admins determine who can create a group. This setting can be found in your site's Dashboard under Groups Application > General Settings > Group Creation. If set to site members with admin approval, site members can create a group using the createGroup() function, and the group becomes a createRequest with a name of PENDING. The site admin either approves or rejects the request to create a group. If set to all site members, site members can create a group using the createGroup() function (no approval required). If set to only admins, only site admins can create a group using the createGroup() function. The default is set to site members with admin approval.

When a group is created, the newly created group is added to the Groups List page of your site.

The Groups API provides functionality allowing you to:

  • Create a new group.
  • Delete an existing group.
  • Get group information by ID.
  • Get group information by slug.
  • List all groups.
  • Query groups.
  • Update group information.

Permissions Information

Note: You can override the permissions below by using the wix-auth elevate() function.

FunctionsPermissions
createGroup()Manage in your site's Dashboard. Note: If you override this permission with the elevate() function, you must provide a creatorId when running the function.
deleteGroup(), updateGroup()Site admin, group admin.
listGroups(), getGroup(), queryGroups()For public & private groups: any site member. For secret groups: group members, site admin.

Warning: Elevating a function allows it to be called by any site visitor. Exercise caution to prevent security vulnerabilities.

To use the Groups API, import groups from wix-groups.v2:

Copy
import { groups } from "wix-groups.v2";
Did this help?

createGroup( )


Creates a group.

The createGroup() function returns a Promise that resolves to a newly-created group after it has successfully been created. The new group is added to the Groups List page of your site.

Site admins can choose to allow site members to create a group. They can also require that site members request their approval when creating a group. This setting can be found in your site's Dashboard under Groups Application > General Settings > Group Creation. If set to admin approval required, a site member uses this function to create a group, and the group becomes a createRequest with a status of PENDING until the group is reviewed. The default is set to site members with admin approval.

Method Declaration
Copy
function createGroup(group: Group, options: CreateGroupOptions): Promise<Group>;
Method Parameters
groupGroupRequired

Group to create.


optionsCreateGroupOptions

Optional fields for group creation.

Returns
Return Type:Promise<Group>
JavaScript
import { groups } from "wix-groups.v2"; async function createGroup(group, options) { try { const result = await groups.createGroup(group, options); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?

deleteGroup( )


Deletes a group.

The deleteGroup() function returns a Promise resolves to the deleted group after it has successfully been deleted. Only site admins and group admins can delete their group. After the group is deleted, it is removed from both your site and the site's Dashboard.

Method Declaration
Copy
function deleteGroup(groupId: string): Promise<DeleteGroupResponse>;
Method Parameters
groupIdstringRequired

ID of the group to delete.

Returns
Return Type:Promise<DeleteGroupResponse>
JavaScript
import { groups } from "wix-groups.v2"; async function deleteGroup(groupId) { try { const result = await groups.deleteGroup(groupId); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?

getGroup( )


Gets a group by ID.

The getGroup() function returns a Promise that resolves to a group whose ID matches the given ID.

Note: For SECRET groups, only site admins, group admins, and group members can see a group and its content.

Method Declaration
Copy
function getGroup(groupId: string, options: GetGroupOptions): Promise<Group>;
Method Parameters
groupIdstringRequired

ID of the group to retrieve.


optionsGetGroupOptions
Returns
Return Type:Promise<Group>
JavaScript
import { groups } from "wix-groups.v2"; async function getGroup(groupId, options) { try { const result = await groups.getGroup(groupId, options); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?

getGroupBySlug( )


Gets a group by slug.

The getGroupBySlug() function returns a Promise that resolves to a group whose slug matches the given slug. The slug is the end of a group's URL that refers to a specific group. For example, if a group's URL is https:/example.com/groups/{my-fitness-group}, the slug is my-fitness-group. The slug is case-sensitive. It is generally based on the group name, but for secret groups it is an autogenerated string of characters, for example, https:/example.com/groups/{5D3yTX}.

Note: For SECRET groups, only site admins, group admins, and group members can see a group and its content.

Method Declaration
Copy
function getGroupBySlug(
  slug: string,
  options: GetGroupBySlugOptions,
): Promise<GetGroupBySlugResponse>;
Method Parameters
slugstringRequired

Unique part of the group's URL, for example group-1 in https:/example.com/groups/group-1. Pass only the slug. Case-sensitive.


optionsGetGroupBySlugOptions
Returns
Return Type:Promise<GetGroupBySlugResponse>
JavaScript
import { groups } from "wix-groups.v2"; async function getGroupBySlug(slug, options) { try { const result = await groups.getGroupBySlug(slug, options); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?

listGroups( )


Lists groups.

The listGroups() function returns a Promise that resolves to a list of up to 1,000 groups on your site. Sorts by default to _createdDate in descending order.

Notes:

  • For SECRET groups, only site admins, group admins, and group members can see a list of group and their content.
  • This function's parameters are positional, and must be specified in the sequence shown in the syntax below. When specifying a parameter, use null as a placeholder for any unspecified parameters. For example, to specify limit only, call listGroups(paging, null).
Method Declaration
Copy
function listGroups(options: ListGroupsOptions): Promise<ListGroupsResponse>;
Method Parameters
optionsListGroupsOptions

Limit and offset options.

Returns
Return Type:Promise<ListGroupsResponse>
JavaScript
import { groups } from "wix-groups.v2"; async function listGroups(options) { try { const result = await groups.listGroups(options); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?

queryGroups( )


Creates a query to retrieve a list of groups.

Note: For SECRET groups, only site admins, group admins, and group members can query groups and their content.

The queryGroups() function builds a query to retrieve a list of all groups, and returns a GroupsQueryBuilder object.

PROPERTYSUPPORTED FILTERS & SORTING
titleeq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
membersCountascending(),descending()
_createdDateascending(),descending()
recentActivityDateascending(),descending()
Method Declaration
Copy
function queryGroups(options: QueryGroupsOptions): GroupsQueryBuilder;
Method Parameters
optionsQueryGroupsOptions
Returns
Return Type:GroupsQueryBuilder
JavaScript
import { groups } from "wix-groups.v2"; async function queryGroups() { const { items } = groups.queryGroups().find(); }
Did this help?

updateGroup( )


Updates a group.

The updateGroup() function returns a Promise that resolves to the updated group. Only site admins and group admins can update their group. Only the fields in the groupInfo object parameter can be updated. Specify which fields to update. Unspecified fields remain the same.

Notes:

  • When a group's privacyStatus is updated from PRIVATE to PUBLIC, all pending join requests for that group are automatically approved.
  • When a group's privacyStatus is updated from PRIVATE to SECRET, all pending join requests for that group are automatically rejected.
  • When a public or private group's name is updated, the slug is updated to reflect the new group name.
Method Declaration
Copy
function updateGroup(
  _id: string,
  group: UpdateGroup,
  options: UpdateGroupOptions,
): Promise<Group>;
Method Parameters
_idstringRequired

Group ID.


groupUpdateGroupRequired

optionsUpdateGroupOptions
Returns
Return Type:Promise<Group>
JavaScript
import { groups } from "wix-groups.v2"; async function updateGroup(id, group, options) { try { const result = await groups.updateGroup(id, group, options); return result; } catch (error) { console.error(error); // Handle the error } }
Did this help?