Players:BanAsync

The Players:BanAsync() method allows you to easily ban users who violate your experience's guidelines. You can specify the ban duration, enable the ban to propagate to suspected alternate accounts, and provide a message to the banned user in accordance with the Usage Guidelines. You should also post your experience rules somewhere accessible to all users and provide a way for them to appeal. This method is enabled and disabled by the Players.BanningEnabled property, which you can toggle in Studio.

Banning and Messaging

Banned users will be immediately evicted and prevented from rejoining your experiences. They will be presented with an error modal displaying the time left on their ban and your DisplayReason. Roblox's backend systems will evict players across all servers from the place(s) that you specify. DisplayReason can have a maximum length of 400 characters and is subject to a text filter. For more information on acceptable modal text, see ban messaging.

Places and Universe

By default, bans extend to any place within that universe. To limit the ban to only the place from which this API is called, configure ApplyToUniverse to false. However, if a user is banned in the start place of the universe, it effectively results in the user being excluded from the entirety of the universe, irrespective of whether a universal ban is in place or not.

Alternative Accounts

Users often play under multiple different accounts, known as alternate accounts or alt accounts, which are sometimes used to circumvent account bans. To help you keep banned users out, the default behavior of this API will propagate all bans from the source account you banned to any of their suspected alt accounts. You can turn off ban propagations to alt accounts by configuring ExcludeAltAccounts to true.

Ban Duration

Not all transgressions are the same, so not all bans should be the same length. This API lets you configure the duration of the ban, in seconds, with the Duration field. To specify a permanent ban, set the field to -1. You may also want to dynamically configure the ban duration based on the user's ban history, which you can query for using Players:GetBanHistoryAsync(). For example, you may want to consider the number of bans, the duration of previous bans, or build logic off of the notes you save under PrivateReason which can be up to 1000 characters and are not text filtered. PrivateReason notes are never shared with the client and can be considered safe from attackers.

Errors and Throttling

This method invokes an HTTP call to backend services which are subject to throttling and may fail. If you're calling this API with more than one UserId, this method will attempt to make the HTTP call for each ID. It will then aggregate any error messages and join them as a comma separated list. For example, if this method is invoked for five users and requests for those with UserIds 2 and 4 fail, the following error message appears:

HTTP failure for UserId 2: Timedout, HTTP 504 (Service unavailable) failure for UserId 4: Service exception

The message will always include failure for UserId {} if it is an HTTP error.

Client-Side Requirement

Because of the risks associated with banning users, this method may only be called on the backend experience server (client-side calls will result in an error). You may test this API in Studio, during collaborative creation, or in a team test, but the bans will not apply to production.

This API uses the User Restrictions Open Cloud API. You will be able to utilize these APIs to manage your bans in third party applications.

Parameters

Returns

local Players = game:GetService("Players")

if shouldBeBanned(player: Player) then
	local banHistoryPages = Players:GetBanHistoryAsync(player.UserId)
	local duration = getNextBanDuration(banHistoryPages)  -- Creator-implemented logic
	local config: BanConfigType = {
		UserIds = {player.UserId},
		Duration = duration,
		DisplayReason = "You violated community guideline #5",
		PrivateReason = "Put anything here that the user should not know but is helpful for your records",
		ExcludeAltAccounts = false,
		ApplyToUniverse = true
	}

	local success, err = pcall(function()
		return Players:BanAsync(config)
	end)
	print(success, err)
end