Last Updated: 7/19/2021, 8:46:25 AM

# Party

# Overview

The AccelByte Lobby Service includes Party features to enable multiplayer play. All Party features use WebSocket to ensure smooth communication between players. Players can interact with parties in several ways, including:

  • User Party Info shows players information about their party, including the Party ID, Leader ID, and the list of Party Members.
  • Create Party allows players to create a new party that other players can join.
  • Invite to Party allows players to invite their friends to join their party. Both the inviter and invitee will receive a notification when the invitation is sent.
  • Join Party allows players to join a party that they’ve been invited to join. When the player joins the party the inviter and other party members will be notified.
  • Reject Party Invitation allows players to reject a party invitation. The inviter will be notified that their invitation was rejected.
  • Promote Member as a Party Leader allows players to set another player as the party leader.
  • Kick Party allows party leaders to remove another player from their party.

# Party Storage

Game Client needs to be able to store party properties such as Party ID and Party Member in a JSON form. Lobby service will collect the party properties, and game servers will write custom attributes based on the needs. See the diagram below to know how party storage works.

party

# Permissions

Make sure you’re authorized to use our services and have the following permissions (opens new window) before you attempt to manage party:

Usage Resource Action Admin Get All Parties ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read Admin Get Party Data ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read Update Party Attributes ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Update Admin Get User Party Data ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE Read

# Managing Party with the SDK

# Create a Party

Players can create a party that can be used for matchmaking. A player can only create one party at a time, and will become the leader of the party they create.

# Invite to Party

Players can invite other players to their party, as long as the invited player is not already in a party. Party invitees will receive a notification that they have been invited to join a party and current party members will also receive a notification that someone has been invited to the party. Party invitees are identified by the inviteeUserId parameter in the Unity SDK and by inviteePlayerId in the UE4 SDK.

# Join a Party

Players that are invited to a party can accept the invitation and join the party. Party invitees will receive a notification that they’ve joined the party and current party members will also receive a notification that someone is joining the party. The party is identified by the partyID parameter and the invitation by the invitationToken parameter.

# Reject a Party Invitation

When a player has been invited to a party, they can choose to reject the invitation. Party invitees will receive a notification that they’ve rejected the invitation and current party members will also receive a notification that someone has rejected the party invitation. The party is identified by the partyID parameter and the invitation by the invitationToken parameter.

# Promote a Member as the Party Leader

The party leader can promote another party member to become the new party leader. All party members will be notified of the new party leader. The new party leader is identified by the memberUserId parameter.

# Kick Players From a Party

The party leader has the privilege to remove a party member from their party by kicking them out of the party. Kicked party member will receive a notification that they’ve been kicked out of the party, and current party members will also receive a notification that someone has been kicked from the party. The kicked party member is identified by the memberUserId parameter in Unity and by KickPlayerId in UE4.

# Leave a Party

Party members can choose to leave their party. If the party leader leaves the party, party leadership will be passed to another party member automatically. Party members that leave the party will receive a notification that they’ve left the party and current party members will also receive a notification that someone is leaving the party.

# Party Storage

Party Storage enables a party to store party attributes that can be passed from the game server to the game client. The game server will write the party’s storage to ensure that all party members get the same information or notification from the server.

# Party Data Update Notification

Use this function to notify players of any updates to party data. Party members will be notified if an event occurs in the party, such as when a player accepts a party invitation, joins the party, or leaves the party.

# Get Party Data (Client-Side)

Use this function to retrieve specific party data from the client side. Make sure you have players logged in to allow this API call.

# Get Party Data (Server-Side)

Use this function to retrieve specific party data from the server side. Make sure the game server is authenticated to allow this API call.

# Retrieve Active Parties

This function will retrieve active parties from the game server side. The game server must be authenticated to allow this API call.There are two types of functions you can use to retrieve active parties:

In the first function, you can define the limit and offset in the beginning.

In the second function, you can retrieve the active party on the next page using the previous pagination.

# Write Party Data

Write Party Data is an exclusive feature for the game server. In writing party data, it can occur that multiple servers write to the same party at the same time. To avoid this, our SDK has a timestamp in the backend to ensure that the latest write data will never be overwritten with older data.

# Managing Party using the API

You can also use our API endpoints to manage parties.

# Get All-Party Data in a Namespace

You can get all-party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get All Parties: GET - /lobby/v1/admin/party/namespaces/{namespace}/parties (opens new window) endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the desired values into the Offset and Limit fields if you want the results to be paginated.

Upon a successful request, the party data will be retrieved. Here is the response example of the successful request:

[
  {
    "custom_attribute": {},
    "invitees": [
      "string"
    ],
    "leader": "string",
    "members": [
      "string"
    ],
    "namespace": "string",
    "partyId": "string",
    "updatedAt": 0
  }
]

# Get Party Data

You can get specific party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get Party Data: GET - /lobby/v1/admin/party/namespaces/{namespace}/parties/{partyId} (opens new window) endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the Party ID.

Upon a successful request, the party data will be retrieved. Here is the response example of the successful request:

{
  "custom_attribute": {},
  "invitees": [
    "string"
  ],
  "leader": "string",
  "members": [
    "string"
  ],
  "namespace": "string",
  "partyId": "string",
  "updatedAt": 0
}

# Update Party Attributes

You can update party attributes using the API. To do so, follow steps below:

  1. Use the Update Party Attributes: PUT - /lobby/v1/public/party/namespaces/{namespace}/parties/{partyId}/attributes (opens new window) endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the Party ID.
  4. Fill out the Response Body: - Input the Custom Attribute with the attributes you want to update.

Upon a successful request, the party attributes will be updated. Here is the response example of the successful request:

{
  "custom_attribute": {},
  "invitees": [
    "string"
  ],
  "leader": "string",
  "members": [
    "string"
  ],
  "namespace": "string",
  "partyId": "string",
  "updatedAt": 0
}

# Get User Party Data

You can get specific party data in a namespace using the API. To do so, follow steps below:

  1. Use the Admin Get User Party Data: GET - /lobby/v1/admin/party/namespaces/{namespace}/users/{userId}/party (opens new window) endpoints.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the User ID of the user you want to get the party data.

Upon a successful request, the party data of the user will be retrieved. Here is the response example of the successful request:

{
  "custom_attribute": {},
  "invitees": [
    "string"
  ],
  "leader": "string",
  "members": [
    "string"
  ],
  "namespace": "string",
  "partyId": "string",
  "updatedAt": 0
}
{
  • For more information about the Party service, you can access this API Reference (opens new window).
  • Learn about our Chat service, which let’s party members interact with each other.
  • Check out our Matchmaking guide to see how parties can be matched to play against each other.
  • Players can form parties with their friends if you integrate our Friends service into your game.