Usage Guide for Messaging

Messaging Service API is the Open Cloud equivalent to Lua MessagingService, which enables you to communicate across servers or client instances of your experience. As the Lua API only allows you to write and update a script manually in Studio for publishing messages, you can use the Open Cloud API to send messages to live servers from external tools to automate and improve your experience operation workflows.

Usage

There are several helpful tools that you can build by supporting cross-server communication with Messaging Service API, including:

  • Announcement Portals: A web portal can be helpful to support sending announcements to all users across servers in your experience, such as announcing an upcoming event, an update, and the winner for a competition. On the portal, you can edit a message and click a button that calls the API to send the message out for all users or selected users.

  • Moderation System: A moderation system can help keep your experience safe and secure. When detecting a user with inappropriate behavior, you can publish a message to trigger the experience server to warn or ban the specific user. You can also support data stores in the moderation system to add user accounts to a blocklist that prevents them from rejoining.

  • LiveOps Dashboard: LiveOps Dashboard is a useful tool for managing live events, such as a Halloween party. On the LiveOps dashboard, you can pre-code an event, update event messages, trigger the event when it's ready, and reward selected users with special items like a virtual crown without updating any of the experience's code.

Setting up a Topic for Messaging

Before you can publish a message to all of your experience's live servers, you need to set up a topic, which is a customized message channel that is accessible from multiple servers. After defining a topic, you need to subscribe users to the topic for receiving your incoming messages.

Currently, you can only define a topic in Studio and use Lua MessagingService:SubscribeAsync() to subscribe users to it. The following code sample subscribes any user to a topic when they join the experience:

Set up and Subscribe Users to a Topic

local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")
local function onPlayerAdded(player)
-- Define and subscribe to the topic
local topic = "YourTopic"
local connection = MessagingService:SubscribeAsync(topic, function(message)
print(message.Data)
end)
player.AncestryChanged:Connect(function()
-- Unsubscribe from the topic upon player ancestry change
connection:Disconnect()
end)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Publishing Messages to Live Servers

After setting up a topic, you can publish a message to all of your experience's live servers with the following steps:

  1. Create an API key on Creator Dashboard. Make sure you perform the following settings:

    1. Add Messaging Service API to Access Permissions.
    2. Add Publish operation to your selected experience.
  2. Get the Universe ID, the identifier of the experience in which you want to send your messages to.

    1. Navigate to the Creations page on the Creator Dashboard.
    2. Find the experience that you want to publish your messages to.
    3. Click the ... button on the target experience's thumbnail to display a list of options, then select Copy Universe ID from the list.
  3. Add the API Key in the x-api-key header of a POST request to the API like the following example:

    Example Request for Publishing a Message

    curl \
    --location \
    --request POST \
    'https://apis.roblox.com/messaging-service/v1/universes/{universeId}/topics/{topic}' \
    -H 'x-api-key: abc...' \
    -H 'Content-Type: application/json' \
    --data-raw '{"message":"message to publish"}'
  4. Call the API to send the message out.