rojo/.cursor/rules/roblox/reference/engine/classes/SocialService.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: SocialService
type: class
memory_category: Instances
summary: |
  Facilitates social functions that impact relationships made on the Roblox
  platform.
description: |
  **SocialService** facilitates social functions that impact relationships made
  on the Roblox platform. Its primary usage is to show
  [invite prompts](../../../production/promotion/invite-prompts.md) and the
  phone book to players, allowing them to send invitation requests to their
  connections through
  `Class.SocialService:PromptGameInvite()|PromptGameInvite()` and
  `Class.SocialService:PromptPhoneBook()|PromptPhoneBook()` respectively. You
  may leverage signals when such requests are made.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
  - NotReplicated
deprecation_message: ''
properties: []
methods:
  - name: SocialService:CanSendCallInviteAsync
    summary: |
      Indicates whether the given `Class.Player` can invite other players to a
      call.
    description: |
      Returns `true` if the given `Class.Player` can send a call invite to a
      connection. You should always use the result of this method before calling
      `Class.SocialService:PromptPhoneBook()|PromptPhoneBook()` since the
      ability to open the phone book may vary depending on the player.

      See [Roblox Connect](../../../resources/roblox-connect.md) for a sample
      implementation of this method.
    code_samples:
      - SocialService-PromptPhoneBook
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` instance of the player potentially sending a call
          invite.
    returns:
      - type: boolean
        summary: |
          Whether the specified player can send a call invite.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:CanSendGameInviteAsync
    summary: |
      Indicates whether the given `Class.Player` can invite other players.
    description: |
      `Class.SocialService:CanSendGameInviteAsync()|CanSendGameInviteAsync()`
      returns `true` if the given `Class.Player` can invite other players to the
      current experience. You should always use the result of this method before
      calling `Class.SocialService:PromptGameInvite()|PromptGameInvite()` since
      the ability to invite players may vary depending on the platform or
      player.

      See
      [Player Invite Prompts](../../../production/promotion/invite-prompts.md)
      for more details on implementing player invite prompts, customizing
      prompts and notifications, and using launch data.
    code_samples:
      - sending-a-game-invite
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` instance of the player potentially sending an
          invite.
      - name: recipientId
        type: int64
        default: 0
        summary: |
          Optional `Class.Player.UserId` of the potential **recipient**, used to
          check whether the sender can invite that specific recipient.
    returns:
      - type: boolean
        summary: |
          Whether the specified player can send an invite.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:GetEventRsvpStatusAsync
    summary: |
      Returns the local player's RSVP status for the given event.
    description: |
      Returns the local player's RSVP status for the given event. Events must be
      in the current experience and must not have already started. If the event
      has already started, this method will return an error.

      Note that you can use
      `Class.SocialService:PromptRsvpToEventAsync()|PromptRsvpToEventAsync()` to
      prompt the player to change their RSVP status for the event.
    code_samples:
      - SocialService-PromptRsvpToEventAsync
    parameters:
      - name: eventId
        type: string
        default:
        summary: |
          The event ID of the event to prompt the player to change their RSVP
          status for. This must be a valid event ID that exists in the current
          experience, represented as a string (not a number).
    returns:
      - type: RsvpStatus
        summary: |
          Returns an `Enum.RsvpStatus` indicating the player's current RSVP
          status for the event. If the player has not RSVP'd to the event, this
          will return `Enum.RsvpStatus.None`.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:GetExperienceEventAsync
    summary: |
      Returns details for the specified experience event or `nil` if it is
      unavailable.
    description: |
      `GetExperienceEventAsync()` yields until the request completes and then
      returns a dictionary describing the requested event. The dictionary
      contains the following fields:

      - `Id` (string)
      - `Title` (string)
      - `Description` (string)
      - `StartTime` (dictionary)
        - `Day` (number)
        - `Year` (number)
        - `Month` (number)
        - `Minute` (number)
        - `Millisecond` (number)
        - `Hour` (number)
        - `Second` (number)
      - `EndTime` (dictionary)
        - `Day` (number)
        - `Year` (number)
        - `Month` (number)
        - `Minute` (number)
        - `Millisecond` (number)
        - `Hour` (number)
        - `Second` (number)
      - `HasStarted` (boolean)
      - `HasEnded` (boolean)
      - `Status` (`Enum.ExperienceEventStatus`)
      - `UserRsvpStatus` (`Enum.RsvpStatus` or `nil`)

      If the event cannot be found, belongs to a different experience, or the
      response is malformed, this method returns `nil`. Requests may also fail
      with a `HttpError <status>` message if the service returns an unexpected
      error code.
    code_samples:
      - SocialService-GetUpcomingExperienceEventsAsync
    parameters:
      - name: eventId
        type: string
        default:
        summary: |
          The string identifier of the event to retrieve. Must correspond to an
          event in the current experience.
    returns:
      - type: Dictionary?
        summary: |
          A dictionary describing the event, or `nil` if the event does not
          exist, belongs to another experience, or is otherwise unavailable.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:GetPartyAsync
    summary: |
      Returns an array of dictionaries containing data for all members of the
      specified party who are currently in the experience.
    description: |
      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:

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

      To test this service in your experience, use the
      [Party Simulator](../../../studio/testing-modes.md#party-simulation) in
      Roblox Studio or publish the experience and play it in the Roblox
      application.
    code_samples:
      - SocialService-GetPartyAsync
    parameters:
      - name: partyId
        type: string
        default:
        summary: ''
    returns:
      - type: Array
        summary: |
          An array of dictionaries representing the members of the specified
          party who are currently in the experience.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:GetPlayersByPartyId
    summary: |
      Returns a table of all presently connected `Class.Player` objects whose
      `Class.Player.PartyId` property matches the passed `partyId`.
    description: |
      Returns a table of all presently connected `Class.Player` objects whose
      `Class.Player.PartyId` property matches the provided `partyId`. This
      method behaves similarly to `Class.Players:GetPlayers()` but filters the
      results to include only those players belonging to the specified party.

      To test this service in your experience, use the
      [Party Simulator](../../../studio/testing-modes.md#party-simulation) in
      Roblox Studio or publish the experience and play it in the Roblox
      application.
    code_samples:
      - SocialService-GetPlayersByPartyId
      - Party-Team-Integration
    parameters:
      - name: partyId
        type: string
        default:
        summary: ''
    returns:
      - type: Instances
        summary: |
          A table of `Class.Player` objects whose `Class.Player.PartyId`
          property matches the passed `partyId`.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:GetUpcomingExperienceEventsAsync
    summary: |
      Returns active and upcoming experience events for the current experience.
    description: |
      `GetUpcomingExperienceEventsAsync()` yields while the client requests data
      for the current experience and then returns an array of dictionaries, each
      with the same structure described in
      `Class.SocialService:GetExperienceEventAsync()|GetExperienceEventAsync()`.
      The array includes only events that are currently active or have not yet
      ended, excluding cancelled, moderated, or unpublished events. Results are
      sorted so the soonest start time appears first.

      If the service indicates there are no matching events, this method returns
      an empty array. Requests may raise a `HttpError <status>` message if the
      service returns an unexpected error code.
    code_samples:
      - SocialService-GetUpcomingExperienceEventsAsync
    parameters: []
    returns:
      - type: Array
        summary: |
          An array of dictionaries describing each active or upcoming event in
          the current experience, ordered by soonest start time first.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:HideSelfView
    summary: |
      Hides the calling player's self view.
    description: |
      Hides the calling player's self view. If this method is called while the
      self view is already hidden, it does nothing.
    code_samples: []
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptFeedbackSubmissionAsync
    summary: |
      Prompts the player to submit feedback about the current experience.
    description: |
      Displays a feedback submission dialog to the player, allowing them to
      provide feedback about their experience. The submitted feedback becomes
      available to developers in the Creator Dashboard under the **Audience** >
      **Feedback** section.

      Players can submit feedback once per day per experience. Experience owners
      cannot submit feedback for their own experiences. If the player has
      already submitted feedback for the day, owns the experience, or is
      otherwise ineligible, the prompt will display a message indicating that
      feedback is unavailable.

      This method yields until the player either submits feedback or dismisses
      the dialog. As an asynchronous operation, it should be called using
      `task.spawn()` or within a coroutine.

      Note that this service does not work during playtesting in Roblox Studio.
      To test the feedback prompt, you must publish the experience and play it
      in the Roblox application.
    code_samples:
      - PromptFeedbackSubmissionAsync
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptGameInvite
    summary: |
      Prompts the given `Class.Player` with the invite screen.
    description: |
      `Class.SocialService:PromptGameInvite()|PromptGameInvite()` displays an
      invite prompt to the local player through which they may invite their
      connections to the current experience. Before calling this method, you
      should use
      `Class.SocialService:CanSendGameInviteAsync()|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](../../../production/promotion/invite-prompts.md)
      for more details on implementing invite prompts, customizing prompts and
      notifications, and using launch data.
    code_samples:
      - sending-a-game-invite
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` to prompt with the invite popup.
      - name: experienceInviteOptions
        type: Instance
        default: nil
        summary: |
          Optional `Class.ExperienceInviteOptions` object for customizing the
          prompt.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptLinkSharingAsync
    summary: ''
    description: |
      This call is restricted to server scripts. After a link is successfully
      generated, the target player will either be prompted to open a share sheet
      with the generated link, or the link will be copied directly to the
      clipboard if share sheet functionality is not available to the player.

      ```lua
      local HttpService = game:GetService("HttpService")
      local SocialService = game:GetService("SocialService")

      local success, result  = pcall(function()
      	local data = {
          	promoCode = "j7du67"
      	}

      	local launchData = HttpService:JSONEncode(data)

      	local LinkSharingOptions = {
      		ExpirationSeconds = 20000,
      		PreviewTitle = "Awesome Game",
      		PreviewDescription = "Lets play together",
      		LaunchData = launchData,
      	}

      	return SocialService:PromptLinkSharingAsync(player, LinkSharingOptions)
      end)

      if not success or result ~= Enum.PromptLinkSharingResult.Success then
      	warn("PromptLinkSharingAsync failed:", tostring(result))
      end
      ```
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          Prompts the given `Class.Player` with a Roblox platform-level share
          sheet with a generated share link.
      - name: options
        type: Dictionary
        default: nil
        summary: |
          `Dictionary` that specifies the configuration for the generated link.
          It includes the following optional key-value pairs:

          - `FallbackLinkId` (string). Determines how this share link will
            direct player to once expired. Default to experience join link.
          - `ExpirationSeconds` (number). Determines time to expiration once the
            share link is created. Truncates to nearest integer. Defaults to
            86,400.
          - `PreviewTitle` (string) Preview title of the share link.
          - `PreviewDescription` (string) Preview description of the share link.
          - `PreviewAssetId` (number) Image asset ID used for share link
            preview.
          - `LaunchData` (string). Used to set a parameter in
            `Class.Player:GetJoinData()` when a player joined using the
            generated share link.
    returns:
      - type: Tuple
        summary: |
          A tuple containing an `Enum.PromptLinkSharingResult` indicating the
          result of the link sharing prompt.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptLinkSharing
    summary: ''
    description: ''
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: |
          Prompts the given `Class.Player` with a Roblox platform-level share
          sheet with a generated share link.
      - name: options
        type: Dictionary
        default: nil
        summary: |
          `Dictionary` that specifies the configuration for the generated link.
          It includes the following optional key-value pairs:

          - `FallbackLinkId` (string). Determines how this share link will
            direct player to once expired. Default to experience join link.
          - `ExpirationSeconds` (number). Determines time to expiration once the
            share link is created. Truncates to nearest integer. Defaults to
            86,400.
          - `PreviewTitle` (string) Preview title of the share link.
          - `PreviewDescription` (string) Preview description of the share link.
          - `PreviewAssetId` (number) Image asset ID used for share link
            preview.
          - `LaunchData` (string). Used to set a parameter in
            `Class.Player:GetJoinData()` when a player joined using the
            generated share link.
    returns:
      - type: Tuple
        summary: |
          A tuple containing an `Enum.PromptLinkSharingResult` indicating the
          result of the link sharing prompt.
    tags:
      - Yields
      - Deprecated
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptPhoneBook
    summary: |
      Prompts the given `Class.Player` with the phone book.
    description: |
      Prompts the given `Class.Player` with the phone book. If the player
      chooses to call someone, the
      `Class.SocialService.CallInviteStateChanged|CallInviteStateChanged` event
      fires. You should use
      `Class.SocialService:CanSendCallInviteAsync()|CanSendCallInviteAsync()`
      prior to calling `Class.SocialService:PromptPhoneBook()|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](../../../resources/roblox-connect.md) for a sample
      implementation of this method.
    code_samples:
      - SocialService-PromptPhoneBook
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The player to prompt with the phone book.
      - name: tag
        type: string
        default:
        summary: |
          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.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:PromptRsvpToEventAsync
    summary: |
      Prompts the local `Class.Player` with a prompt to change their RSVP status
      to the given event.
    description: |
      `PromptRsvpToEventAsync()` displays a prompt to the local player through
      which they may change their RSVP status to the given event.

      Events must be in the current experience and must not have already
      started. If the event has already started, this method will return an
      error.

      Note that you can use
      `Class.SocialService:GetEventRsvpStatusAsync()|GetEventRsvpStatusAsync()`
      to check the player's current RSVP status before calling this method.
    code_samples:
      - SocialService-PromptRsvpToEventAsync
    parameters:
      - name: eventId
        type: string
        default:
        summary: |
          The event ID of the event to prompt the player to change their RSVP
          status for. This must be a valid event ID that exists in the current
          experience, represented as a string (not a number).
    returns:
      - type: RsvpStatus
        summary: |
          Returns a `Enum.RsvpStatus` indicating the player's new RSVP status
          after the prompt is closed. If the player closes the prompt without
          changing their RSVP status, this will return `Enum.RsvpStatus.None` or
          their old `Enum.RsvpStatus` if they had already selected a status.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
  - name: SocialService:ShowSelfView
    summary: |
      Shows the calling player's self view.
    description: |
      Shows the calling player's self view. If this method is called while the
      self view is already visible, it does nothing.
    code_samples: []
    parameters:
      - name: selfViewPosition
        type: SelfViewPosition
        default: LastPosition
        summary: |
          The position to place the self view .
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
events:
  - name: SocialService.CallInviteStateChanged
    summary: |
      Fires when a player's call invite state changes.
    description: |
      This event fires when a player's call invite state changes.
    code_samples:
      - SocialService-CallInviteStateChanged
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` instance of the player who had a call invite state
          change.
      - name: inviteState
        type: InviteState
        default:
        summary: |
          The new call invite state.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Social
  - name: SocialService.GameInvitePromptClosed
    summary: |
      Fires when a player closes an invite prompt.
    description: |
      This event fires when a player closes an invite prompt.
    code_samples: []
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` instance of the player who closed the prompt.
      - name: recipientIds
        type: Array
        default:
        summary: |
          No longer populated; an empty array.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Social
  - name: SocialService.PhoneBookPromptClosed
    summary: |
      Fires when a player closes the phone book prompt.
    description: |
      Fires when a player closes the phone book prompt.
    code_samples: []
    parameters:
      - name: player
        type: Instance
        default:
        summary: |
          The `Class.Player` instance of the player who closed the phone book.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Social
  - name: SocialService.ShareSheetClosed
    summary: ''
    description: ''
    code_samples: []
    parameters:
      - name: player
        type: Player
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Social
callbacks:
  - name: SocialService.OnCallInviteInvoked
    summary: |
      Callback for when a call is placed from the phone book.
    description: |
      A callback to process when a call is placed from the phone book. The `tag`
      parameter can be used to differentiate between different "entry points" or
      similar, as described in
      `Class.SocialService:PromptPhoneBook()|PromptPhoneBook()`. Only one
      callback can be set.
    code_samples:
      - SocialService-OnCallInviteInvoked
    parameters:
      - name: tag
        type: string
        default:
        summary: |
          String to help differentiate between various phone book entry points.
      - name: callParticipantIds
        type: Array
        default:
        summary: |
          Array containing all of the players involved in the call. The caller
          will always be the first player in the array.
    returns:
      - type: Instance
        summary: |
          Table including the `PlaceId` and `ReservedServerAccessCode` keys
          whose values are the `Class.DataModel.PlaceId` and the server access
          code returned by `Class.TeleportService:ReserveServerAsync()`,
          respectively.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Social
    writeCapabilities: []