Setup

To use the Groups API, install the @wix/groups package using npm or Yarn:

Copy
1
npm install @wix/groups

or

Copy
1
yarn add @wix/groups

Then import { groups } from @wix/groups:

Copy
1
import { groups } from '@wix/groups'
Was this helpful?
Yes
No

Introduction

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.
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
groupGroupRequired
Group to create.

optionsCreateGroupOptions
Optional fields for group creation.
Response Object
CreateGroupResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
groupIdstringRequired
ID of the group to delete.
Response Object
DeleteGroupResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
groupIdstringRequired
ID of the group to retrieve.
Response Object
GetGroupResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
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.
Response Object
GetGroupBySlugResponse
Was this helpful?
Yes
No

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).

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
optionsListGroupsOptions
Limit and offset options.
Response Object
ListGroupsResponse
Was this helpful?
Yes
No

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()

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Request
This method does not take any parameters
Response Object
GroupsQueryBuilder
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Social Groups
Learn more about permission scopes.
Params
_idstringRequired
Group ID.

groupUpdateGroupRequired
Response Object
UpdateGroupResponse
Was this helpful?
Yes
No