Workplace from Meta is going away. You will be able to continue using Workplace until 31 August 2025. Visit our Help Center to find out more.

Group

Path `/{group-id}`

Represents a Workplace group. The /{group-id} node returns a single group.

Multi-company groups

There are specific considerations which should be taken into account when accessing multi-company groups:

Group content can be read by any app of integration installed in a company that is part of a multi-company group
Multi-company groups are listed in communities or groups alongside regular groups
- The purpose field can be used to identify multi-company groups. This value be set to WORK_MULTI_COMPANY
Group members can also be queried, but only id, name and picture will be visible if an app is from a different company to the user
Integrations with the Manage group permission can add and remove multi-company group members
- Integrations can only add and remove users who are members of the community which the integration is installed on
- Integrations can only add and remove users when one of the group admins is a member of the community which the integration is installed on
An integration with the Manage group content permission can delete content contained within a multi-company group if either:
- The content belongs to a member of the app community or
- A member of the app community is a group admin
Publishing to multi-company groups is currently not available
Multi-company groups can be selected in the group scoping setting for integrations
Bots cannot be mentioned in multi-company groups

Reading

You can read information about a group by making a Graph API GET request to /{group-id}.

Permissions

Reading Group node requires the Read group content permission.

Fields

Field Name	Description	Data Type
`id`	The group ID.	`string`
`cover`	Information about the Group's cover photo.	`CoverPhoto`
`cover_url`	A URL containing an image for the group cover photo.	`string`
`description`	A brief description of the group.	`string`
`icon`	The URL for the group's icon.	`url`
`is_workplace_default`	Indicates whether the group is a default Workplace group (read only).	`boolean`
`is_community`	Indicates whether the group is also a community and can contain other groups (read only).	`boolean`
`name`	The name of the group.	`string`
`owner`	The member that created this group.	`User`
`privacy`	The privacy setting of the group. Possible values: `CLOSED` `OPEN` `SECRET`	`string`
`updated_time`	The last time the group was updated. This includes any changes in the group's properties and changes in posts and comments.	`datetime`
`archived`	Indicates whether the group was archived.	`boolean`
`post_requires_admin_approval`	Indicates whether posts to the group will require admin approval.	`boolean`
`purpose`	Indicates the purpose of the group	`enum {WORK_ANNOUNCEMENT, WORK_FEEDBACK, WORK_TEAMWORK, WORK_SOCIAL, WORK_MULTI_COMPANY}` Deprecated: `WORK_FOR_SALE, WORK_TEAM`
`post_permissions`	Indicates if a post requires admin approval.	`enum {NONE, ADMIN_ONLY}`
`join_setting`	Indicates how new members can join the group.	`enum {NONE, ANYONE, ADMIN_ONLY}`
`sorting_setting`	Indicates the order of posts returned for `/feed` edges, defaults to `CHRONOLOGICAL`.	`enum {RECENT_ACTIVITY, CHRONOLOGICAL}`
`is_official_group`	Indicates whether the group is an Official Workplace Group. An official-group icon will appear alongside the official group’s name in product.	`boolean`

Publishing

You can't publish using this edge. In order to create a group, publish to the /community/groups edge.

Deleting

You can't delete a group using this node. Removing the last member of a group will delete that group automatically.

Updating

You can update a group by making a Graph API POST request to /{group-id} and passing values for the fields to be updated in the request body.

Permissions

Making updates to a group node requires the Manage groups permission.

Edges

Edge Name	Description
`/admins`	The admins of a Workplace group. Addition and Deletion of admins supported on Workplace. Refer examples given below.
`/albums`	The photo albums in a Workplace group.
`/auto_membership_rules`	The rules for adding members automatically to a group.
`/docs`	The docs in a Workplace group.
`/events`	The events in a Workplace group.
`/feed`	The posts in a Workplace group, arranged into a feed.
`/files`	The files shared into a Workplace group.
`/member_requests`	The pending membership requests for groups that have membership approvals enabled.
`/members`	The members of a Workplace group. This edge exposes: administrator: Shown if this person is an admin of the group joined: Shown when this user joined the group moderator: Shown if this person is a moderator of the group added_by: Shown who added this user to the group
`/moderators`	The moderators of a Workplace group.
`/pinned_posts`	The post pinned to the group.
`/groups`	List any child groups (only applicable to groups which are also communities)

Examples

Get group id, name, archive status, and privacy:

GET graph.facebook.com
  /{group-id}?fields=id,name,archived,privacy

Archive a group:

POST graph.facebook.com
  /{group-id}?archive=true

Get group members with name, id, and join date:

GET graph.facebook.com
  /{group-id}/members?fields=name,id,joined

Get a group's admins and moderators in a single call:

GET graph.facebook.com
  /{group-id}?fields=admins,moderators

Get group docs:

GET graph.facebook.com
  /{group-id}/docs

Get group posts:

GET graph.facebook.com
  /{group-id}/feed

Get group posts in last updated order:

GET graph.facebook.com
  /{group-id}/feed?sorting_setting=RECENT_ACTIVITY

Parameters

sorting_setting

Allows ordering of posts by the time they were last updated instead of created when set to RECENT_ACTIVITY. The default behaviour can be set explicitly by using CHRONOLOGICAL as value. Updates may include edits to the post as well as a comment or reaction having been added.

Get group posts including additional attachments like videos, images, files, or polls:

GET graph.facebook.com
  /{group-id}/feed?fields=attachments

Poll options are listed in descending order according to vote count for each option.

Get a list of group members, along with their join date:

GET graph.facebook.com
  /{group-id}/members?fields=name,joined

Add a member to a group by id:

POST graph.facebook.com
  /{group-id}/members/{member-id}

Add a member to a group by email:

POST graph.facebook.com
  /{group-id}/members?email=michael%40example.com

When including email addresses in the URL for a request, ensure that the email addresses is URL encoded. Example: michael@example.com becomes michael%40example.com.

Removing the last member from a group will schedule that group for deletion.

Remove a member from a group by id:

DELETE graph.facebook.com
  /{group-id}/members/{member-id}

Remove a member from a group by email:

DELETE graph.facebook.com
  /{group-id}/members?email=michael%40example.com

When including email addresses in the URL for a request, ensure that the email addresses is URL encoded. Example: michael@example.com becomes michael%40example.com.

Promote a member to admin of a group:

POST graph.facebook.com
  /{group-id}/admins/{user-id}

Demote an admin to member of a group:

DELETE graph.facebook.com
  /{group-id}/admins/{user-id}

Create a new Event in a group:

POST graph.facebook.com
  /{group-id}/events
  ?name=New+Event
  &start_time=2017-03-02T14:00:04+00:00
  &end_time=2017-03-02T15:00:04+00:00
  &description=Test+Description
  &location=Boardroom

Upload a new photo (via binary) to a group:

POST graph.facebook.com
  /{group-id}/photos?source={image-data}

Upload a new photo (via url) to a group:

POST graph.facebook.com
  /{group-id}/photos?url={image-data}

Create group posts with image & video attachments:

POST graph.facebook.com
  /{group-id}/feed?attached_media=[{"media_fbid":"{photo-id}"},{"media_fbid":"{photo-id}"}]

Parameters

attached_media

Used for photos & videos, an array of media_fbids wrapped in braces. Supports the following image formats: .jpeg, .bmp, .png, .gif, .tiff. More information about image formats can be found here. Supported video files can be found here. To obtain media_fbids for images, please publish unpublished photos to https://graph.facebook.com/me/photos first, as described in the documentation here. To obtain media_fbids for videos (including animated GIFs), please publish videos first to https://graph.facebook.com/me/videos?no_story=true.

Setting the paramater no_story to true suppresses the feed story that is automatically generated on a person’s profile when they upload a video using your app.

Create group posts with file attachments:

POST graph.facebook.com
  /{group-id}/feed?files=[{file-id},{file-id}]

Parameters

files

Used for files, an array of file_ids (note they are not wrapped in braces). File versioning is not currently supported. To update files, please remove the original file from the post attachments and re-upload a new file attachment. Supports the following file formats:

Documents: .pdf, .csv, .tsv, .docx, .pptx, .xlsx
Images: .jpeg, .png
Videos: .mp4
Archives: .rar, .zip

To obtain file_ids, please publish files to https://graph.facebook.com/group_file_revisions first. You may publish source files locally from your computer.

You cannot combine the attached_media and files parameters in one API call. This mimics behavior in the group composer, which has separate options for uploading a 'Photo/Video' and 'File'.

Update the post permissions, join settings, purpose and post approval settings

POST graph.facebook.com
  /{group-id}/?post_permissions=NONE&join_setting=ADMIN_ONLY&purpose=WORK_SOCIAL&post_requires_admin_approval=false

Get the reactions and comments to the pinned post

GET graph.facebook.com
  /{group-id}/pinned_posts?fields=reactions,comments

Identify whether a group is also a community

GET graph.facebook.com
  /{group-id}?fields=is_community

Get the membership rules to a group

GET graph.facebook.com
  /{group-id}/auto_membership_rules

Example Response (JSON):

{
  "data": [
    {
      "conditions": [
        {
          "field": "TITLE",
          "operator": "CONTAINS",
          "values": [
            "sales"
          ]
        }
      ],
      "id": RULE_ID
    }
  ],
  ...
}

Delete an auto membership rule for a group

DELETE graph.facebook.com
  /RULE_ID

Apply a membership rule to a group

POST graph.facebook.com
  /{group-id}/auto_membership_rules

Example Payload:

{
    "conditions": [
        {
            "field": "LOCATION",
            "operator": "CONTAINS",
            "values": ["London", "San Francisco"]
        }
    ]
  }

This API has the potential of adding thousands of users to a group if a mistake is made, so it’s extremely important to use this carefully and double-check before executing the API call.

Get Group ID and Official Group Status:

GET graph.facebook.com
  /{group-id}?fields=id,is_official_group

Update Official Group Status:

POST graph.facebook.com
  /{group-id?is_official_group={FALSE | TRUE}

Group

Path /{group-id}

Multi-company groups

Reading

Permissions

Fields

Publishing

Deleting

Updating

Permissions

Edges

Examples

Get group id, name, archive status, and privacy:

Archive a group:

Get group members with name, id, and join date:

Get a group's admins and moderators in a single call:

Get group docs:

Get group posts:

Get group posts in last updated order:

Get group posts including additional attachments like videos, images, files, or polls:

Get a list of group members, along with their join date:

Add a member to a group by id:

Add a member to a group by email:

Remove a member from a group by id:

Remove a member from a group by email:

Promote a member to admin of a group:

Demote an admin to member of a group:

Create a new Event in a group:

Upload a new photo (via binary) to a group:

Upload a new photo (via url) to a group:

Create group posts with image & video attachments:

Create group posts with file attachments:

Update the post permissions, join settings, purpose and post approval settings

Get the reactions and comments to the pinned post

Identify whether a group is also a community

Get the membership rules to a group

Delete an auto membership rule for a group

Apply a membership rule to a group

Get Group ID and Official Group Status:

Update Official Group Status:

Path `/{group-id}`