# 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: MessagingService
type: class
memory_category: Instances
summary: |
  Allows servers of the same experience to communicate with each other.
description: |
  **MessagingService** allows servers of the same experience to communicate with
  each other in real time (less than 1 second) using topics. Topics are
  developer‑defined strings (1–80 characters) that servers use to send and
  receive messages.

  Delivery is best effort and not guaranteed. Make sure to architect your
  experience so delivery failures are not critical.

  [Cross-Server Messaging](../../../cloud-services/cross-server-messaging.md)
  explores how to communicate between servers in greater detail.

  If you want to publish ad-hoc messages to live game servers, or publish across
  experiences, you can use the
  [Open Cloud APIs](../../../cloud/guides/usage-messaging.md).

  #### Limitations

  Note that these limits are subject to change.

  <table>
  	<thead>
  		<tr>
  			<th>Limit</th>
  			<th>Maximum</th>
  		</tr>
  	</thead>
  	<tbody>
  		<tr>
  			<td>
  				<b>Size of message</b>
  			</td>
  			<td>
  				1kB
  			</td>
  		</tr>
  		<tr>
  			<td>
  				<b>Messages sent per game server</b>
  			</td>
  			<td>
  				 600 + 240 * (number of players in this game server) per minute
  			</td>
  		</tr>
  		<tr>
  			<td>
  				<b>Messages received per topic</b>
  			</td>
  			<td>
  				(40 + 80 * number of servers) per minute
  			</td>
  		</tr>
  		<tr>
  			<td>
  				<b>Messages received for entire game</b>
  			</td>
  			<td>
  				 (400 + 200 * number of servers) per minute
  			</td>
  		</tr>
      <tr>
  			<td>
  				<b>Subscriptions allowed per game server</b>
  			</td>
  			<td>
  				 20 + 8 * (number of players in this game server)
  			</td>
  		</tr>
      <tr>
  			<td>
  				<b>Subscribe requests per game server</b>
  			</td>
  			<td>
  				 240 requests per minute
  			</td>
  		</tr>
  	</tbody>
  </table>
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
  - NotReplicated
deprecation_message: ''
properties: []
methods:
  - name: MessagingService:PublishAsync
    summary: |
      Invokes the supplied callback whenever a message is pushed to the topic.
    description: |
      This function sends the provided message to all subscribers to the topic,
      triggering their registered callbacks to be invoked.

      Yields until the message is received by the backend.
    code_samples: []
    parameters:
      - name: topic
        type: string
        default:
        summary: |
          Determines where the message is sent.
      - name: message
        type: Variant
        default:
        summary: |
          The data to include in the message.
    returns:
      - type: ()
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - ServerCommunication
  - name: MessagingService:SubscribeAsync
    summary: |
      Begins listening to the given topic.
    description: |
      This function registers a callback to begin listening to the given topic.
      The callback is invoked when a topic receives a message. It can be called
      multiple times for the same topic.

      #### Callback

      The callback is invoked with a single argument, a table with the following
      entries:

      <table>
      	<thead>
      		<tr>
      			<th>Field</th>
      			<th>Summary</th>
      		</tr>
      	</thead>
      	<tbody>
      		<tr>
      			<td>
      				<b>Data</b>
      			</td>
      			<td>
      				Developer supplied payload
      			</td>
      		</tr>
      		<tr>
      			<td>
      				<b>Sent</b>
      			</td>
      			<td>
      				Unix time in seconds at which the message was sent
      			</td>
      		</tr>
      	</tbody>
      </table>

      It yields until the subscription is properly registered and returns a
      connection object.

      To unsubscribe, call `Datatype.RBXScriptConnection|Disconnect()` on the
      returned object. Once called, the callback should never be invoked.
      Killing the script containing the connections also causes the underlying
      connect to be unsubscribed.

      See also `Class.MessagingService:PublishAsync()` which sends the provided
      message to all subscribers to the topic, triggering their registered
      callbacks to be invoked.
    code_samples:
      - subscribing-to-cross-server-messages
    parameters:
      - name: topic
        type: string
        default:
        summary: |
          Determines where to listen for messages.
      - name: callback
        type: Function
        default:
        summary: |
          Function to be invoked whenever a message is received.
    returns:
      - type: RBXScriptConnection
        summary: |
          Connection that can be used to unsubscribe from the topic.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - ServerCommunication
events: []
callbacks: []