SocialService

Methods

GetPlayersByPartyId(partyId : string):Instances
Returns a table of all presently connected Player objects whose Player.PartyId property matches the passed partyId.
HideSelfView():()
Hides the calling player's self view.
PromptGameInvite(player : Instance,experienceInviteOptions : Instance):()
Prompts the given Player with the invite screen.
PromptPhoneBook(player : Instance,tag : string):()
Prompts the given Player with the phone book.
ShowSelfView(selfViewPosition : Enum.SelfViewPosition):()
Shows the calling player's self view.
CanSendCallInviteAsync(player : Instance):boolean
Yields
Indicates whether the given Player can invite other players to a call.
CanSendGameInviteAsync(player : Instance,recipientId : number):boolean
Yields
Indicates whether the given Player can invite other players.
GetPartyAsync(partyId : string):Array
Yields
Returns an array of dictionaries containing data for all members of the specified party who are currently in the experience.

Events

CallInviteStateChanged(player : Instance,inviteState : Enum.InviteState):RBXScriptSignal
Fires when a player's call invite state changes.
GameInvitePromptClosed(player : Instance,recipientIds : Array):RBXScriptSignal
Fires when a player closes an invite prompt.
PhoneBookPromptClosed(player : Instance):RBXScriptSignal
Fires when a player closes the phone book prompt.

Callbacks

OnCallInviteInvoked(tag : string,callParticipantIds : Array):Instance
Callback for when a call is placed from the phone book.

Properties

Methods

GetPlayersByPartyId

Instances

Returns a table of all presently connected Player objects whose Player.PartyId property matches the provided partyId. This method behaves similarly to Players:GetPlayers() but filters the results to include only those players belonging to the specified party.

Note that this service does not work during playtesting in Roblox Studio; to test aspects of your experience using it, you must publish the experience and play it in the Roblox application.

Parameters

partyId: string

Default Value: ""

Returns

Instances

A table of Player objects whose Player.PartyId property matches the passed partyId.

Code Samples

The following example listens for when a player joins the experience. If the player is part of a party, it uses SocialService:GetPlayersByPartyId() to retrieve all players in the same party who are currently connected to the server. It then outputs the name of each party member.

SocialService:GetPlayersByPartyId()

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local partyId = player.PartyId

	if partyId ~= "" then
		local partyPlayers: { Player } = SocialService:GetPlayersByPartyId(partyId)

		for _, partyMember in partyPlayers do
			print("Party Member: " .. partyMember.Name)
		end
	else
		warn("Player is not in a party")
	end
end)

This code sample demonstrates how to assign players to Teams based on their Player.PartyId using the SocialService:GetPlayersByPartyId() method. When a player joins the experience, the script checks whether they're part of a party. If so, it attempts to assign them to the same team as other party members. If no match is found or the player isn't in a party, they're placed on the team with fewer members to maintain balance.

Team Rebalance with Party Integration

local Teams = game:GetService("Teams")
local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local redTeam = Instance.new("Team")
redTeam.Name = "Red Team"
redTeam.TeamColor = BrickColor.Red()
redTeam.AutoAssignable = false
redTeam.Parent = Teams

local blueTeam = Instance.new("Team")
blueTeam.Name = "Blue Team"
blueTeam.TeamColor = BrickColor.Blue()
blueTeam.AutoAssignable = false
blueTeam.Parent = Teams

local function assignPlayerToTeam(player)
  local partyId = player.PartyId

  if partyId == "" then
    assignBalancedTeam(player)
    return
  end

  local teams = { redTeam, blueTeam }
  local matchingTeam = nil
  local partyPlayers = SocialService:GetPlayersByPartyId(partyId)

  for _, partyPlayer in partyPlayers do
    if partyPlayer ~= player and table.find(teams, partyPlayer.Team) then
      matchingTeam = partyPlayer.Team
      break
    end
  end

  if matchingTeam then
    player.Team = matchingTeam
    player.TeamColor = matchingTeam.TeamColor
  else
    assignBalancedTeam(player)
  end
end

function assignBalancedTeam(player)
  local redCount = #redTeam:GetPlayers()
  local blueCount = #blueTeam:GetPlayers()
  local chosenTeam = redCount <= blueCount and redTeam or blueTeam

  player.Team = chosenTeam
  player.TeamColor = chosenTeam.TeamColor
end

local function groupPlayersByParty()
  local seenPartyIds = {}
  local groupedPlayers = {}

  for _, player in Players:GetPlayers() do
    if player.PartyId == "" then
      table.insert(groupedPlayers, { player })
    elseif not table.find(seenPartyIds, player.PartyId) then
      table.insert(seenPartyIds, player.PartyId)

      local partyPlayers = SocialService:GetPlayersByPartyId(player.PartyId)
      table.insert(groupedPlayers, partyPlayers)
    end
  end

  return groupedPlayers
end

-- Call this function to rebalance teams
local function rebalanceTeams()
  local groups = groupPlayersByParty()

  table.sort(groups, function(a, b)
    return #a > #b
  end)

  for _, player in Players:GetPlayers() do
    player.Team = nil
  end

  for _, group in groups do
    local redCount = #redTeam:GetPlayers()
    local blueCount = #blueTeam:GetPlayers()

    local bestTeam
    if redCount <= blueCount then
      bestTeam = redTeam
    else
      bestTeam = blueTeam
    end

    for _, player in group do
      player.Team = bestTeam
      player.TeamColor = bestTeam.TeamColor
    end
  end

  for _, player in Players:GetPlayers() do
    player:LoadCharacter()
  end
end

Players.PlayerAdded:Connect(function(player)
  assignPlayerToTeam(player)

  player:LoadCharacter()

  player:GetPropertyChangedSignal("PartyId"):Connect(function()
    if player.PartyId ~= "" then
      assignPlayerToTeam(player)
    end
  end)
end)

HideSelfView

()

Hides the calling player's self view. If this method is called while the self view is already hidden, it does nothing.

Returns

()

PromptGameInvite

()

PromptGameInvite() displays an invite prompt to the local player through which they may invite their friends to the current experience. Before calling this method, you should use CanSendGameInviteAsync() to determine whether the player can send an invite, as this ability may vary depending on the platform or player.

See Player Invite Prompts for more details on implementing invite prompts, customizing prompts and notifications, and using launch data.

Parameters

player: Instance

The Player to prompt with the invite popup.

Default Value: ""

experienceInviteOptions: Instance

Optional ExperienceInviteOptions object for customizing the prompt.

Default Value: "nil"

Returns

()

Code Samples

The following code sample uses CanSendGameInviteAsync() to confirm whether the local Player can send an invite. If true, it then prompts the invite using PromptGameInvite().

Sending an Invite

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer

-- Function to check whether the player can send an invite
local function canSendGameInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendGameInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canInvite = canSendGameInvite(player)
if canInvite then
	SocialService:PromptGameInvite(player)
end

PromptPhoneBook

()

Prompts the given Player with the phone book. If the player chooses to call someone, the CallInviteStateChanged event fires. You should use CanSendCallInviteAsync() prior to calling PromptPhoneBook() since the ability to see the phone book may vary depending on the player.

If a player is not eligible to open the phone book, an error dialog is shown.

See Roblox Connect for a sample implementation of this method.

Parameters

player: Instance

The player to prompt with the phone book.

Default Value: ""

tag: string

String to help differentiate between various phone book "entry points" or similar. For example, you can pass a string defining what region of an experience the calling player's character is currently in.

Default Value: ""

Returns

()

Code Samples

The following code sample, placed within a child LocalScript of a GuiButton, uses CanSendCallInviteAsync() to confirm that the player can make a call. If so, it connects PromptPhoneBook() to the button's Activated event.

SocialService:PromptPhoneBook()

local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local player = Players.LocalPlayer
local button = script.Parent
button.Visible = false

-- Function to check whether the player can send a call invite
local function canSendCallingInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendCallInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canCall = canSendCallingInvite(player)
if canCall then
	button.Visible = true
	button.Activated:Connect(function()
		SocialService:PromptPhoneBook(player, "")
	end)
end

ShowSelfView

()

Shows the calling player's self view. If this method is called while the self view is already visible, it does nothing.

Parameters

selfViewPosition: Enum.SelfViewPosition

The position to place the self view .

Default Value: "LastPosition"

Returns

()

CanSendCallInviteAsync

Yields

Returns true if the given Player can send a call invite to a friend. You should always use the result of this method before calling PromptPhoneBook() since the ability to open the phone book may vary depending on the player.

See Roblox Connect for a sample implementation of this method.

Parameters

player: Instance

The Player instance of the player potentially sending a call invite.

Default Value: ""

Returns

Whether the specified player can send a call invite.

Code Samples

SocialService:PromptPhoneBook()

local Players = game:GetService("Players")
local SocialService = game:GetService("SocialService")

local player = Players.LocalPlayer
local button = script.Parent
button.Visible = false

-- Function to check whether the player can send a call invite
local function canSendCallingInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendCallInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canCall = canSendCallingInvite(player)
if canCall then
	button.Visible = true
	button.Activated:Connect(function()
		SocialService:PromptPhoneBook(player, "")
	end)
end

CanSendGameInviteAsync

Yields

CanSendGameInviteAsync() returns true if the given Player can invite other players to the current experience. You should always use the result of this method before calling PromptGameInvite() since the ability to invite players may vary depending on the platform or player.

See Player Invite Prompts for more details on implementing player invite prompts, customizing prompts and notifications, and using launch data.

Parameters

player: Instance

The Player instance of the player potentially sending an invite.

Default Value: ""

recipientId: number

Optional Player.UserId of the potential recipient, used to check whether the sender can invite that specific recipient.

Default Value: 0

Returns

Whether the specified player can send an invite.

Code Samples

The following code sample uses CanSendGameInviteAsync() to confirm whether the local Player can send an invite. If true, it then prompts the invite using PromptGameInvite().

Sending an Invite

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

local player = Players.LocalPlayer

-- Function to check whether the player can send an invite
local function canSendGameInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendGameInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canInvite = canSendGameInvite(player)
if canInvite then
	SocialService:PromptGameInvite(player)
end

GetPartyAsync

Array

Yields

Returns an array of dictionaries containing data for all members associated with the given partyId. The returned array reflects the current state of the party across all active server instances within the experience and it is ordered by the time each party member accepted the party invite. This means the first element in the array is the earliest to accept and the last is the most recent.

This method is useful for retrieving up-to-date information about all party members currently in the experience and across different servers, enabling coordinated group behavior such as teleportation, matchmaking, or party-based gameplay logic.

Each dictionary in the returned array contains the following fields:

Key	Value Type	Description
UserId	number	The player's Player.UserId property.
PlaceId	number	The DataModel.PlaceId of the place the party member is currently in.
JobId	string	The DataModel.JobId of the server instance the user currently resides in.
PrivateServerId	string	If applicable, the DataModel.PrivateServerId when the party member is in a private or reserved server.
ReservedServerAccessCode	string	If applicable, the access code for the reserved server that the user currently resides in. Useful for teleporting party members to each other using TeleportService:TeleportAsync().

Note that this service does not work during playtesting in Roblox Studio; to test aspects of your experience using it, you must publish the experience and play it in the Roblox application.

Parameters

partyId: string

Default Value: ""

Returns

Array

An array of dictionaries representing the members of the specified party who are currently in the experience.

Code Samples

The following example checks if a player is in a party when they join. If so, it retrieves the latest party data using SocialService:GetPartyAsync() and outputs the details of each party member.

SocialService:GetPartyAsync()

local SocialService = game:GetService("SocialService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local partyId = player.PartyId

	if partyId == "" then
		warn("Player is not in a party")
		return
	end

	local success, partyData = pcall(function()
		return SocialService:GetPartyAsync(partyId)
	end)

	if success and partyData then
		for _, partyMemberData in partyData do
			print(
				partyMemberData.UserId,
				partyMemberData.PlaceId,
				partyMemberData.JobId,
				partyMemberData.PrivateServerId,
				partyMemberData.ReservedServerAccessCode
			)
		end
	else
		warn("Failed to retrieve party data")
	end
end)

Events

CallInviteStateChanged

This event fires when a player's call invite state changes.

Parameters

player: Instance

The Player instance of the player who had a call invite state change.

inviteState: Enum.InviteState

The new call invite state.

Code Samples

SocialService.CallInviteStateChanged

local SocialService = game:GetService("SocialService")

local button = script.Parent
local isPhonebookOpen = false

SocialService.CallInviteStateChanged:Connect(function(_, inviteState)
	local isCalling = inviteState == Enum.InviteState.Placed

	if isCalling or isPhonebookOpen then
		button.Visible = false
	else
		button.Visible = true
	end
end)

GameInvitePromptClosed

This event fires when a player closes an invite prompt.

Parameters

player: Instance

The Player instance of the player who closed the prompt.

recipientIds: Array

No longer populated; an empty array.

PhoneBookPromptClosed

Fires when a player closes the phone book prompt.

Parameters

player: Instance

The Player instance of the player who closed the phone book.