App and Game Groups
App and Game Groups uses a number of different objects across the Graph API. This page aggregates all those calls into a single reference so you can easily understand where to find various calls. For a higher-level overview, please see the App and Game Groups Concepts document.
Features
App and Game Groups is designed so that apps can create and manage groups to help people connect and share their experiences. One of the main use cases for Groups is games, which already organize their players into groups through clans, alliances, guilds or other game communities. For this reason, we will refer to the feature as "Game Groups" going forward in this document.
This feature exposes an API to do the following:
- Get all groups that belong to a game.
- Get all groups a user belongs to in a game.
- Create and Delete a group.
- Get all members of a group.
- Invite and Remove a user to/from the group.
- Promote and Remove group admins.
- Create and Get events for the group.
- Set the cover photo for the group.
Game Groups have a privacy setting which controls who sees the group.
- Open (public) groups: Anyone can see the group, who's in it and what members post.
- Closed groups: Anyone can see the group and who's in it but only members can see posts.
- Secret groups: Only members see the group, who's in it and what members post.
API Details
Game Groups
Game Groups are created and controlled by the application.
Read All Groups
Applications can get all the groups that belong to an application by issuing a GET request to /APP_ID/groups with an app access_token.
If the action is successful, the response will be an array that contains elements with the following properties:
| Name | Description | Type |
|---|---|---|
id |
The id of the group. | string |
name |
The name of the group. | string |
Read User Groups
Applications can get all the groups a user belongs in an application by issuing a GET request to /me/groups?parent=APP_ID with a user access_token. This requires the user_groups permission.
If the action is successful, the response is an array in which each element contains:
| Name | Description | Type |
|---|---|---|
id |
The id of the group. | string |
name |
The name of the group. | string |
administrator |
The user is administrator of the group. This field will only be returned if the user is an administrator. | boolean |
Create
Policy: When a user is creating a Game Group there must be explicit messaging in the UI which communicates that the user is also creating a Facebook Group.
Applications create a group issuing a POST request to /APP_ID/groups with an app access_token. Optionally, a user can be set as an admin of a group by setting the admin parameter.
| Parameter | Description | Type | Required |
|---|---|---|---|
name |
A name for the group. | string |
yes |
description |
A description for the group. | string |
no |
privacy |
The privacy setting for the group. | string (open, closed, secret) |
no (default: closed) |
admin |
The user ID of the admin. | string |
no |
If the action is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The id of the group. | string |
Delete
Policy: Developers should build a confirmation action in the user experience to make sure users want to delete groups.
Applications delete a group issuing a DELETE request to /APP_ID/groups/GROUP_ID with an app access_token.
If the group has no members, the group will be irreversibly deleted. If the group has members, the group will no longer be associated with the application and become a normal Facebook Group.
If the action is successful, the response will contain true.
Members
Read
Applications can get the list of members that belong to a group by issuing a GET request to /GROUP_ID/members with an app access_token.
If the action is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The id of the user. | string |
name |
The name of the user. | string |
administrator |
The user is administrator of the group. | boolean |
Invite User
Policy: When a user is joining a Game Group there must be explicit messaging in the UI which communicates that they are also joining a Facebook Group.
Applications can invite users to a group by issuing a POST request to /GROUP_ID/members/USER_ID with an app access_token.
Note that user being invited must be a user of the application. The user will be sent a notification saying that they have been invited to the group. The notification will take them to the group page. Users can only be invited once. Subsequent invites will fail.
Optionally, a from parameter can be passed in the request. If the from parameter is included, then the invite request will look like it was sent by the from user. If this parameter is not included, then the invite request will appear to come from the application. Invites sent on behalf of a user can only be sent to the sender's friends.
| Parameter | Description | Type | Required |
|---|---|---|---|
from |
The ID of the user doing the inviting. | string |
no |
If the action is successful, the response will contain true.
Remove Member
Users can be removed from a group by issuing a DELETE request to GROUP_ID/members/USER_ID with an app access_token.
If the action is successful, the response will contain true.
Promote Admin
A member of a group can be promoted to admin by issuing a POST request to /GROUP_ID/admins/USER_ID with an app access_token. The user must be a member of the group. The user will receive a notification that they have been made an admin for the group.
If the action is successful, the response will contain true.
Remove Admin
A member of a group can be promoted to admin by issuing a DELETE request to /GROUP_ID/admins/USER_ID with an app access_token.
If the action is successful, the response will contain true.
Customize Groups
Post to Feed
Policy: When posting to a group there must be explicit messaging in the UI which communicates that user's content can be accessed by members of the group and is not restricted by their app privacy level.
Users can post a link on the Group's wall by issuing an HTTP POST request to /GROUP_ID/feed with the publish_actions permissions and the following parameters. (publish_stream will also work, but you should use publish_actions.) This requires a user access_token.
| Parameter | Description | Type | Required |
|---|---|---|---|
message |
Post message | string |
either message or link |
link |
Post URL | string |
either message or link |
picture |
Post thumbnail image (can only be used if link is specified) |
string |
no |
name |
Post name (can only be used if link is specified) |
string |
no |
caption |
Post caption (can only be used if link is specified) |
string |
no |
description |
Post description (can only be used if link is specified) |
string |
no |
If the create is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The new post ID | string |
Set Cover Photo
Applications can set the cover photo for a group by issuing a POST request to /GROUP_ID with an app access_token.
| Name | Description | Type | Required |
|---|---|---|---|
cover_url |
The url for the cover photo. The image will be downloaded and added to the group's album and then used as a cover photo. | string |
yes |
If the action is successful, the response will contain true.
Get Events
Applications can get events for a group by issuing a GET request to /GROUP_ID/events with a user access_token.
If the action is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The id of the event. | string |
name |
The name of the event | string |
start_time |
Start time of the event in ISO-8601 format. | string
|
end_time |
End time of the event in ISO-8601 format. | string
|
location |
Location of the event. | string |
Create Event
Users can create an event for a group by issuing a POST request to /GROUP_ID/events with a user access_token. The user needs the create_event permission.
All event times are ISO-8601 formatted strings (e.g., '2012-07-04', '2012-07-04T19:00:00-0700'). Event times containing the time must have the UTC offset.
| Parameter | Description | Type | Required |
|---|---|---|---|
name |
Name of event. | string |
yes |
start_time |
Start time of the event in ISO-8601 format. | string |
yes |
end_time |
End time of the event in ISO-8601 format. | string |
no |
description |
Description of the event. | string |
no |
location |
Location of the event. | string |
no |
location_id |
Facebook Place ID of the place for the event. | string |
no |
If the create is successful, the response will contain:
| Name | Description | Type |
|---|---|---|
id |
The new event ID | string |
Updated about 6 months ago