rojo/.cursor/rules/roblox/reference/engine/classes/TextChatService.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: TextChatService
type: class
memory_category: Instances
summary: |
  A service handling in-experience text chat.
description: |
  A service handling in-experience text chat, including
  `Class.TextChannel|managing channels`, decorating messages, filtering text,
  `Class.TextChatCommand|creating commands`, and
  [developing custom chats interfaces](../../../chat/examples/simple-custom-frontend-ui.md).

  To learn more, see
  [TextChatService Overview](../../../chat/in-experience-text-chat.md).

  For further customization, TextChatService has the following singleton
  children:

  - `Class.ChatWindowConfiguration`
  - `Class.ChatInputBarConfiguration`
  - `Class.BubbleChatConfiguration`
  - `Class.ChannelTabsConfiguration`
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties:
  - name: TextChatService.ChatTranslationEnabled
    summary: |
      Determines whether a user has chat translation enabled.
    description: |
      Determines whether a user has chat translation enabled. If true, messages
      the user receives will be translated into their preferred language. Use
      <code>Class.TextChatMessage.Translation</code> to get the message
      translation.
    code_samples: []
    type: boolean
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: RobloxScriptSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Chat
  - name: TextChatService.ChatVersion
    summary: |
      Determines whether to fully enable `Class.TextChatService` or revert to
      the legacy chat system.
    description: |
      Determines whether to fully enable `Class.TextChatService` or revert to
      the legacy chat system. Setting this property to
      `Enum.ChatVersion.LegacyChatService` effectively disables
      `Class.TextChatService`.
    code_samples: []
    type: ChatVersion
    tags: []
    deprecation_message: |
      This property has been deprecated in newly created Studio experiences.
      `TextChatService` is the only allowed chat system and is automatically
      enabled.
    security:
      read: None
      write: RobloxScriptSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Chat
  - name: TextChatService.CreateDefaultCommands
    summary: |
      Determines whether `Class.TextChatService` should create default
      `Class.TextChatCommand|TextChatCommands`.
    description: |
      Determines whether `Class.TextChatService` should create default
      `Class.TextChatCommand|TextChatCommands`.

      If true, the following `Class.TextChatCommand|TextChatCommands` are
      created and put in a `Class.Folder` named **TextChatCommands** inside
      `Class.TextChatService`:

      <table>
        <thead>
          <tr>
            <th>Name</th>
            <th>Primary Alias</th>
            <th>Secondary Alias</th>
            <th>Description</th>
            <th>Usage Example</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><b>RBXClearCommand</b></td>
            <td>clear</td>
            <td>cls</td>
            <td>Clears the chat log for the local user.</td>
            <td><code>/cls</code></td>
          </tr>
          <tr>
            <td><b>RBXConsoleCommand</b></td>
            <td>console</td>
            <td></td>
            <td>Opens the Developer Console.</td>
            <td><code>/console</code></td>
          </tr>
          <tr>
            <td><b>RBXEmoteCommand</b></td>
            <td>emote</td>
            <td>e</td>
            <td>Plays an avatar emote.</td>
            <td><code>/e dance</code></td>
          </tr>
          <tr>
            <td><b>RBXHelpCommand</b></td>
            <td>help</td>
            <td>?</td>
            <td>Shows a list of chat commands.</td>
            <td><code>/help</code></td>
          </tr>
          <tr>
            <td><b>RBXMuteCommand</b></td>
            <td>mute</td>
            <td>m</td>
            <td>Mutes a user by their <code>Class.Player.Name|Name</code> or <code>Class.Player.DisplayName|DisplayName</code> in all <code>Class.TextChannel|TextChannels</code>.</td>
            <td><code>/m Username</code></td>
          </tr>
          <tr>
            <td><b>RBXTeamCommand</b></td>
            <td>team</td>
            <td>t</td>
            <td>Enters team chat mode where messages are only visible to teammates.</td>
            <td><code>/t</code></td>
          </tr>
          <tr>
            <td><b>RBXUnmuteCommand</b></td>
            <td>unmute</td>
            <td>um</td>
            <td>Unmutes a user by their <code>Class.Player.Name|Name</code> or <code>Class.Player.DisplayName|DisplayName</code> in all <code>Class.TextChannel|TextChannels</code>.</td>
            <td><code>/um Username</code></td>
          </tr>
          <tr>
            <td><b>RBXVersionCommand</b></td>
            <td>version</td>
            <td>v</td>
            <td>Shows the chat version.</td>
            <td><code>/version</code></td>
          </tr>
          <tr>
            <td><b>RBXWhisperCommand</b></td>
            <td>whisper</td>
            <td>w</td>
            <td>Enters whisper mode with another <code>Class.Player</code>.</td>
            <td><code>/w DisplayName</code> or <code>/w @Username</code></td>
          </tr>
        </tbody>
      </table>

      Note that you can edit, create, and remove
      `Class.TextChatCommand|TextChatCommands` even if
      `Class.TextChatService.CreateDefaultCommands|CreateDefaultCommands` is
      true. Also note that mute and unmute commands apply to all
      `Class.TextChannel|TextChannels`.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Chat
  - name: TextChatService.CreateDefaultTextChannels
    summary: |
      Determines whether `Class.TextChatService` should create default
      `Class.TextChannel|TextChannels`.
    description: |
      Determines whether `Class.TextChatService` should create default
      `Class.TextChannel|TextChannels`. If true, a `Class.Folder` named
      **TextChannels** is created inside `Class.TextChatService` at runtime to
      contain the `Class.TextChannel|TextChannels` outlined in the table below.
      Each of the default channels has the described special behavior applied to
      messages using its internally bound `Class.TextChannel.OnIncomingMessage`
      callback function, changing how messages appear when sent through the
      channel. The callback is assigned automatically either at runtime (if the
      `Class.TextChannel` exists) or when the `Class.TextChannel` is created.

      <table>
        <thead>
          <tr>
            <th>Channel</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><b>RBXGeneral</b></td>
            <td><code>Class.TextChannel</code> for player messages. In the chat window, messages are modified such that <code>Class.TextChatMessage.PrefixText|PrefixText</code> receives a <a href="../../../ui/rich-text.md">rich text</a> font color tag to give chatting players their distinctive name color. If <code>Class.Player.Team</code> exists, that <code>Class.Team.TeamColor</code> is used instead of the default name color.</td>
          </tr>
          <tr>
            <td><b>RBXSystem</b></td>
            <td><code>Class.TextChannel</code> for system messages. In the chat window, messages are modified such that <code>Class.TextChatMessage.Text</code> is given a light grey color tag by default, or a red color tag if <code>Class.TextChatMessage.Metadata</code> contains the word <code>"Error"</code>.</td>
          </tr>
          <tr>
            <td><b>RBXTeam[BrickColor]</b></td>
            <td><code>Class.TextChannel</code> for team-specific player messages, created when a <code>Class.Team.TeamColor|TeamColor</code> is in use by any <code>Class.Team</code> within the <code>Class.Teams</code> service. Name of the created channel is <b>RBXTeam</b> followed by the <code>Class.Team.TeamColor|TeamColor</code> name. For example, <b>RBXTeamCrimson</b> is a <code>Class.TextChannel</code> created when there is an active team whose <code>Class.Team.TeamColor|TeamColor</code> property is the "Crimson" <code>Datatype.BrickColor</code>.<br /><br />In the chat window, messages are modified such that <code>Class.TextChatMessage.PrefixText|PrefixText</code> is colored according to the <code>Class.Player.TeamColor|TeamColor</code> and is prepended with <b>[Team]</b>.<br /><br />Team channels create <code>Class.TextSource|TextSources</code> for all non‑<code>Class.Player.Neutral|Neutral</code> players with the matching <code>Class.Team.TeamColor|TeamColor</code>, allowing them to use team‑only chat. Channels are removed if there are no remaining teams with an associated <code>Class.Team.TeamColor|TeamColor</code>.</td>
          </tr>
          <tr>
            <td><b>RBXWhisper:[UserId1]_[UserId2]</b></td>
            <td><code>Class.TextChannel</code> for whisper messages between two players, created when a player uses the <code>/whisper</code> command on another player. For example <b>RBXWhisper:2276836_505306092</b> is a <code>Class.TextChannel</code> for players with <code>Class.Player.UserId|UserIds</code> <b>2276836</b> and <b>505306092</b>. Inside whisper channels are two <code>Class.TextSource|TextSources</code> associated with the respective <code>Class.Player.UserId|UserIds</code>.<br /><br />In the chat window, messages are colored the same as those in <b>RBXGeneral</b> and <code>Class.TextChatMessage.PrefixText</code> is modified to show whether a message was sent from or received by the local user.<br /><br />Whisper channels are removed when either player leaves the experience.</td>
          </tr>
        </tbody>
      </table>

      Note that the default `Class.TextChannel.OnIncomingMessage` callbacks can
      be overwritten. Also note that you can edit, create, and remove
      `Class.TextChannel|TextChannels` even if
      `Class.TextChatService.CreateDefaultTextChannels|CreateDefaultTextChannels`
      is true.

      Messages from different TextChannels can be separated into different tabs
      in the chat window using `Class.ChannelTabsConfiguration`.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Chat
methods:
  - name: TextChatService:CanUserChatAsync
    summary: |
      Determines whether a user has permission to chat in experiences.
    description: |
      Determines whether a user has permission to chat in experiences. Factors
      such as parental control settings may prevent the user from sending
      messages. Errors if the userId is not in the current server. Note that
      this method can be used with all current player
      `Class.Player.UserId|UserIds` in a `Class.Script` with
      `Class.Script.RunContext|RunContext` of `Enum.RunContext.Server` or
      `Enum.RunContext.Legacy`. This method can also be used in a
      `Class.LocalScript` but only with the `Class.Player.UserId|UserId` of the
      local player.
    code_samples: []
    parameters:
      - name: userId
        type: int64
        default:
        summary: ''
    returns:
      - type: boolean
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChatService:CanUsersChatAsync
    summary: |
      Determines whether or not two users would receive messages between each
      other.
    description: |
      Determines whether or not two users would receive messages between each
      other. Factors such as incompatible parental control settings or blocked
      status may prevent the delivery of messages between users
      `Class.TextChannel|TextChannels` internally use this result to determine
      whether to deliver messages between users. Note that this method is only
      available for use in a `Class.Script` with
      `Class.Script.RunContext|RunContext` of `Enum.RunContext.Server` or
      `Enum.RunContext.Legacy`.
    code_samples: []
    parameters:
      - name: userIdFrom
        type: int64
        default:
        summary: ''
      - name: userIdTo
        type: int64
        default:
        summary: ''
    returns:
      - type: boolean
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChatService:CanUsersDirectChatAsync
    summary: |
      Determines whether a user has permission to chat directly with other users
      in experiences based on factors such as their parental control settings.
    description: |
      Determines whether a user has permission to chat directly with other users
      in experiences based on their parental control settings. To be used when:

      - The line of communication is user-initiated (not developer- or
        gameplay-initiated)
      - Access to the communication is closed and limited

      An example of a direct chat is a whisper channel between two users.

      You may use this method to gate certain features in your experience
      depending on the result.

      When creating a `Class.TextChannel` for a direct chat, use
      `Class.TextChannel:SetDirectChatRequester` to set the requesterUserId so
      that the channel can determine whether to deliver messages between users.
      When `Class.TextChannel.DirectChatRequester` is non-nil,
      `Class.TextChannel|TextChannels` internally use this result to determine
      whether to deliver messages between users.

      ```lua
      local whoCanDirectChat = TextChatService:CanUsersDirectChatAsync(requesterUserId, { userId1, userId2 })

      if #whoCanDirectChat > 0 then
        -- The requesterUserId can direct chat with either userId1, userId2, or both
      else
        -- The requesterUserId cannot direct chat with either userId1 or userId2
      end
      ```

      Note that this method is only available for use in a `Class.Script` with
      `Class.Script.RunContext|RunContext` of `Enum.RunContext.Server` or
      `Enum.RunContext.Legacy`.
    code_samples:
      - TextChatService-User-Chat
    parameters:
      - name: requesterUserId
        type: int64
        default:
        summary: |
          The user who would have initiated the direct chat request. If the
          requesterUserId is not in the current server, this method will error.
      - name: userIds
        type: Array
        default:
        summary: |
          A list of users who the requesterUserId would like to chat with
          directly. Users not in the current server are ignored.
    returns:
      - type: Array
        summary: |
          A list of users who could participate in the direct chat request. If
          none of the users can direct chat with the requesterUserId, the result
          is an empty array.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChatService:DisplayBubble
    summary: |
      Displays a chat bubble above the provided part or player character.
    description: |
      Displays a chat bubble above the provided part or player character, and
      fires the `Class.TextChatService.BubbleDisplayed|BubbleDisplayed` event
      with the parameters specified in this method. Can display bubbles for
      non-player characters (NPCs) if you specify a part within the character,
      such as its head.

      Note that this method is only available for use in `Class.LocalScript`, or
      in a `Class.Script` with `Class.Script.RunContext|RunContext` of
      `Enum.RunContext.Client`.
    code_samples: []
    parameters:
      - name: partOrCharacter
        type: Instance
        default:
        summary: |
          The part or character that the bubble to be displayed above.
      - name: message
        type: string
        default:
        summary: |
          The text to be displayed in the chat bubble.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
events:
  - name: TextChatService.BubbleDisplayed
    summary: |
      Fires when `Class.TextChatService:DisplayBubble()` is called.
    description: |
      Fires when `Class.TextChatService:DisplayBubble()` is called.
    code_samples: []
    parameters:
      - name: partOrCharacter
        type: Instance
        default:
        summary: ''
      - name: textChatMessage
        type: TextChatMessage
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Chat
  - name: TextChatService.MessageReceived
    summary: |
      Fires when `Class.TextChannel:DisplaySystemMessage()` is invoked on the
      client, or when the client receives a valid
      `Class.TextChannel:SendAsync()` response from the server.
    description: |
      Like `Class.TextChannel.MessageReceived`, fires when
      `Class.TextChannel:DisplaySystemMessage()` is invoked on the client, or
      when the client receives a valid `Class.TextChannel:SendAsync()` response
      from the server. This event is only fired on the client.

      If the server's `Class.TextChannel.ShouldDeliverCallback` property is
      bound and returns `false`, the client will not fire
      `Class.TextChatService.MessageReceived`.

      Use the `Class.TextChatMessage` parameter to get the `Class.TextSource`
      and the text of the message (with `Class.TextChatMessage.Text`).

      The `Class.TextChatMessage` parameter is the final result of any functions
      bound to `Class.TextChatService.OnIncomingMessage` or
      `Class.TextChannel.OnIncomingMessage`.
    code_samples: []
    parameters:
      - name: textChatMessage
        type: TextChatMessage
        default:
        summary: |
          The received `Class.TextChatMessage`.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Chat
  - name: TextChatService.SendingMessage
    summary: |
      Fires when `Class.TextChannel:SendAsync()` is called by the sending
      client.
    description: |
      Fires when `Class.TextChannel:SendAsync()` is called by the sending
      client. Use this to allow placeholder messages to be shown to the user
      while waiting for server response to `Class.TextChannel:SendAsync()`.
    code_samples: []
    parameters:
      - name: textChatMessage
        type: TextChatMessage
        default:
        summary: |
          The `Class.TextChatMessage` from the `Class.TextChannel:SendAsync()`
          call.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Chat
callbacks:
  - name: TextChatService.OnBubbleAdded
    summary: |
      Called when a bubble chat is about to be displayed.
    description: |
      Called when a bubble chat is about to be displayed. This can only be
      implemented on the client.

      Use this to customize individual bubble chat messages. If this callback
      returns a `Class.BubbleChatMessageProperties`, those properties will be
      applied to the associated bubble, overriding
      `Class.BubbleChatConfiguration` properties. If a `Class.UICorner`,
      `Class.UIGradient`, or `Class.ImageLabel` is parented under
      `Class.BubbleChatMessageProperties`, they will also override their
      respective counterparts defined in `Class.BubbleChatConfiguration`.

      If the chat message is sent by a player, `message.TextSource` will
      correspond to that player, and `adornee` will be `nil`.

      If the chat message is sent via `Class.TextChatService:DisplayBubble`,
      `adornee` will be the `partOrCharacter` provided, and `message.TextSource`
      will be `nil`.

      When bound to the client sending a message, this callback is run twice:
      first when the message is initially sent and received locally, then again
      when the client receives the result of the filtered message from the
      server.
    code_samples: []
    parameters:
      - name: message
        type: TextChatMessage
        default:
        summary: |
          The incoming `Class.TextChatMessage`.
      - name: adornee
        type: Instance
        default:
        summary: |
          The part or character the bubble chat message is attached to.
    returns:
      - type: Tuple
        summary: |
          If a `Class.BubbleChatMessageProperties` is returned, its properties
          override the `Class.BubbleChatConfiguration` properties.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
    writeCapabilities: []
  - name: TextChatService.OnChatWindowAdded
    summary: |
      Called when a new message is about to be displayed in the chat window.
      This can only be implemented on the client.
    description: |
      Called when a new message is about to be displayed in the chat window.
      This can only be implemented on the client.

      Use this to customize individual messages that appear in the chat window.
      If this callback returns a `Class.ChatWindowMessageProperties`, those
      properties will be applied to the associated message, overriding
      `Class.ChatWindowConfiguration` properties. If a `Class.UIGradient` is
      parented under `Class.ChatWindowMessageProperties`, it will also override
      the `Class.ChatWindowConfiguration.TextColor3|TextColor3` property defined
      in `Class.ChatWindowConfiguration`.

      When bound to the client sending a message, this callback is run twice:
      first when the message is initially sent and received locally, then again
      when the client receives the result of the filtered message from the
      server.
    code_samples: []
    parameters:
      - name: message
        type: TextChatMessage
        default:
        summary: |
          The incoming `Class.TextChatMessage`.
    returns:
      - type: Tuple
        summary: |
          If a `Class.ChatWindowMessageProperties` is returned, its properties
          override the `Class.ChatWindowConfiguration` properties.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
    writeCapabilities: []
  - name: TextChatService.OnIncomingMessage
    summary: |
      Called when `Class.TextChatService` is receiving an incoming message.
    description: |
      Called when `Class.TextChatService` is receiving an incoming message. Can
      only be implemented on the client.

      Use this to decorate `Class.TextChatMessage|TextChatMessages`. If this
      callback returns a `Class.TextChatMessageProperties`, those properties are
      merged with the `Class.TextChatMessage` parameter to create a new
      `Class.TextChatMessage`.

      When bound to the client sending a message, this callback is run twice;
      first when the message is initially sent and received locally, and again
      when the client receives the result of the filtered message from the
      server.

      Note that this `Class.TextChatService.OnIncomingMessage` callback runs
      **before** any `Class.TextChannel.OnIncomingMessage` callbacks.

      This should be defined only once in the source code. Multiple bindings
      will override one another in a non‑deterministic manner.
    code_samples: []
    parameters:
      - name: message
        type: TextChatMessage
        default:
        summary: |
          The incoming `Class.TextChatMessage`.
    returns:
      - type: Tuple
        summary: |
          If a `Class.TextChatMessageProperties` is returned, those properties
          are merged with the `Class.TextChatMessage` parameter to create a new
          `Class.TextChatMessage` with those properties, otherwise, if `nil` is
          returned, then `Class.TextChatMessage` is not changed.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
    writeCapabilities: []