# 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: TextChannel
type: class
memory_category: Instances
summary: |
  Represents a text chat channel.
description: |
  Represents a text chat channel. Contains `Class.TextSource|TextSources` as
  descendants.

  To send a chat message to the `Class.TextChannel`, call
  `Class.TextChannel:SendAsync()` from a `Class.LocalScript`. The corresponding
  `Class.TextSource` of the user with `TextSource.CanSend = true` must be in
  that channel.

  Messages from different TextChannels can be separated into different tabs in
  the chat window using `Class.ChannelTabsConfiguration`.

  To learn more, see
  [In-Experience Text Chat](../../../chat/in-experience-text-chat.md).
code_samples: []
inherits:
  - Instance
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: TextChannel.DirectChatRequester
    summary: |
      The `TextChannel` will only deliver messages to users that can send direct
      messages to the `DirectChatRequester`.
    description: |
      The `TextChannel` will only deliver messages to users that can send direct
      messages to the `DirectChatRequester`. This property can only be set using
      `Class.TextChannel.SetDirectChatRequester()|SetDirectChatRequester()`.
    code_samples: []
    type: Player
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - Chat
methods:
  - name: TextChannel:AddUserAsync
    summary: |
      Adds a `Class.TextSource` to the `Class.TextChannel` given userId of a
      `Class.Player`.
    description: |
      Adds a `Class.TextSource` to the `Class.TextChannel` given userId of the
      user (with `Class.Player.UserId`). Can only be used in a `Class.Script`.

      If a `Class.TextSource` representing the user does not exist, this adds a
      `Class.TextSource`.

      If a `Class.TextSource` representing the user does exist, this returns the
      `Class.TextSource`.

      If the user has chat off or isn't in the server, this returns a tuple
      `nil`, `false`.
    code_samples: []
    parameters:
      - name: userId
        type: int64
        default:
        summary: |
          The userId of the `Class.Player`.
    returns:
      - type: Tuple
        summary: |
          Returns `Class.TextSource` and `true` if a new `Class.TextSource` is
          created for the user, `Class.TextSource` and `false` if there is an
          existing `Class.TextSource`, or `nil` and `false` if the user has chat
          off or is not in this server.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChannel:DisplaySystemMessage
    summary: |
      Displays a system message to the user.
    description: |
      Displays a system message to user. Can only be used in a
      `Class.LocalScript`, or in a `Class.Script` with
      `Class.Script.RunContext|RunContext` of `Enum.RunContext.Client`. Messages
      are only visible to that user and aren't automatically filtered or
      localized.
    code_samples: []
    parameters:
      - name: systemMessage
        type: string
        default:
        summary: |
          The system message sent to the `Class.TextChannel`.
      - name: metadata
        type: string
        default:
        summary: |
          Use to identify system message types, such as the default system
          messages.
    returns:
      - type: TextChatMessage
        summary: |
          A `Class.TextChatMessage` with `Class.TextChatMessage.Status` property
          that indicates the condition of the message.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChannel:SendAsync
    summary: |
      Sends a `Class.TextChatMessage` to the server.
    description: |
      Sends a `Class.TextChatMessage` to the server. Can only be used in a
      `Class.LocalScript`, or in a `Class.Script` with
      `Class.Script.RunContext|RunContext` of `Enum.RunContext.Client`.

      The `metadata` argument has a limit of 200 characters. If this is called
      with a `metadata` argument that has more than 200 characters, the message
      will not be sent to other users. Instead, the sender will receive a
      `Class.TextChatMessage` with the `Class.TextChatMessage.Metadata` and
      `Class.TextChatMessage.Text` properties set to empty strings.
    code_samples: []
    parameters:
      - name: message
        type: string
        default:
        summary: |
          The message to send to the `Class.TextChannel`.
      - name: metadata
        type: string
        default:
        summary: |
          Custom metadata to attach to the message.
    returns:
      - type: TextChatMessage
        summary: |
          A `Class.TextChatMessage` with `Class.TextChatMessage.Status` property
          that indicates the condition of the message.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
  - name: TextChannel:SetDirectChatRequester
    summary: |
      Sets the `Class.TextChannel.DirectChatRequester|DirectChatRequester` for
      the `TextChannel`. The `TextChannel` will only deliver messages to users
      that can send direct messages to the `DirectChatRequester`.
    description: |
      Sets the `Class.TextChannel.DirectChatRequester|DirectChatRequester` for
      the `TextChannel`. This method is only available for use in server
      scripts.

      Use this API if you are working with `Class.TextChatService` and have a
      custom implementation of direct chat outside of the default text channels.

      When called on a `TextChannel` that is parented to `TextChatService` and
      has no existing `TextSources`, `SetDirectChatRequester` adds the requested
      users as a `TextSource` and set the `DirectChatRequester` property for the
      channel.

      When `DirectChatRequester` is set, only messages between users that can
      direct chat with the `DirectChatRequester` are delivered.

      ```lua
      local function createWhisperChannel(fromPlayer, toPlayer)
        local whisperChannel = Instance.new("TextChannel")
        whisperChannel:SetDirectChatRequester(fromPlayer)
        whisperChannel:AddUserAsync(toPlayer.UserId)
        -- The TextChannel instance now has two TextSource instances.
        return whisperChannel
      end
      ```
    code_samples: []
    parameters:
      - name: requester
        type: Player
        default:
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
events:
  - name: TextChannel.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.TextChatService.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.TextChannel.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: incomingMessage
        type: TextChatMessage
        default:
        summary: |
          The received `Class.TextChatMessage`.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - Chat
callbacks:
  - name: TextChannel.OnIncomingMessage
    summary: |
      Called when `Class.TextChannel` is receiving an incoming message.
    description: |
      Called when `Class.TextChannel` 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.

      `Class.TextChannel.OnIncomingMessage` callbacks always run **after** the
      `Class.TextChatService.OnIncomingMessage` callback.

      This should be defined only once per `Class.TextChannel` in the source
      code. Multiple bindings to the same channel will override one another in a
      nondeterministic manner.

      When `Class.TextChatService:CreateDefaultTextChannels()` is true, those
      default `Class.TextChannel|TextChannels` have their
      `Class.TextChannel.OnIncomingMessage` callbacks assigned internally in
      order to exhibit special default behavior.
    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.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
    writeCapabilities: []
  - name: TextChannel.ShouldDeliverCallback
    summary: |
      Called for each client when `Class.TextChannel` is receiving an incoming
      message to determine whether or not it should be delivered to that client.
    description: |
      Called for each client when `Class.TextChannel` is receiving an incoming
      message to determine whether or not it should be delivered to that client.
      Can only be defined on the server.

      Once defined, this callback needs to return a truthy value such as `true`,
      `1`, or `"hello"` to deliver the message to said client. If the callback
      returns anything else (including `nil`), the message won't be delivered to
      that client, although the sender will see the message regardless.

      The sender can be referenced by `Class.TextChatMessage.TextSource`, while
      the receiver is the `textSource` argument. Note that the sender and
      receiver can be the same, as the callback iterates through all possible
      receivers.
    code_samples: []
    parameters:
      - name: message
        type: TextChatMessage
        default:
        summary: |
          The message being sent, which also contains the sender of the message.
      - name: textSource
        type: TextSource
        default:
        summary: |
          The `Class.TextSource` of the user who will be receiving the message.
    returns:
      - type: Tuple
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Chat
    writeCapabilities: []