CFRankBotController Module

Install the Module (Marketplace)

You do not need to manually download any files. The module is published on the Roblox Creator Marketplace as a MainModule you can insert directly into your game.

• Open Roblox Studio and the place you want to use CF Rank Bot in.
• Open the Toolbox → switch to the Marketplace tab.
• Search for "CFRankBot MainModule" or use the direct asset:
  https://create.roblox.com/store/asset/101421529909272/CFRankBot-MainModule
• Insert it into your game in (ReplicatedStorage).

Once inserted, you should see a structure similar to:

CFRankBotController (ModuleScript)
CF_Config          (ModuleScript)

You only ever need to edit CF_Config. The main module handles all HTTP logic for you.

Configure CF_Config

CF_Config stores your API key, group ID and an optional default DefaultTriggeredBy label that appears in your logs.

-- // CF_CONFIG \ --

local Config = {}

Config.ApiKey = "YOUR_API_KEY_HERE"
Config.GroupId = 1234567
Config.DefaultTriggeredBy = "In-Game"

return Config

ApiKey – generate this in your CF Rank Bot web portal.
GroupId – your Roblox group ID.
DefaultTriggeredBy – shown in audit logs when no custom value is passed.

Module Functions

All functions return two values:

• success – true if the API call succeeded; false if there was an error.
• data – on success, this is the decoded JSON from the API; on failure, this is an error message string.

Promote

CFRankBotController.Promote(username: string, triggeredBy: string?)

• Promotes the user by one rank in the configured group.
• triggeredBy is optional – if omitted, DefaultTriggeredBy from CF_Config is used.

Demote

CFRankBotController.Demote(username: string, triggeredBy: string?)

• Demotes the user by one rank in the configured group.

SetRank

CFRankBotController.SetRank(username: string, rankId: number, triggeredBy: string?)

• Sets a user to a specific Roblox rank ID by username.
• Throws an error if rankId is not numeric.

SetRankByUserId

CFRankBotController.SetRankByUserId(userId: number, rankId: number, triggeredBy: string?)

• Same as SetRank, but uses Roblox userId instead of username.
• Ideal for XP systems and scripts that already know the player’s UserId.

TestConnection

CFRankBotController.TestConnection()

• Calls the /status endpoint to verify your HTTP + API key + group config are valid.

Example Usage

1. Basic Test in a Server Script

Quick way to check the module is set up correctly:

local Ranker = require(game.ServerScriptService:WaitForChild("CFRankBotController"))

local ok, status = Ranker.TestConnection()
print("Rank API status:", ok, status)

if not ok then
    warn("Something is wrong with your config or API key.")
end

2. Simple Chat Command (!promote)

Promote yourself by saying !promote in chat (for testing or rank training places):

local Ranker = require(game.ServerScriptService:WaitForChild("CFRankBotController"))

game.Players.PlayerAdded:Connect(function(player)
    player.Chatted:Connect(function(msg)
        if msg == "!promote" then
            local success, result = Ranker.Promote(player.Name, "In-Game Command")

            if success then
                print("Promoted", player.Name)
            else
                warn("Promotion failed:", result)
            end
        end
    end)
end)

3. Set Rank by UserId (XP / Level System)

Example of using SetRankByUserId when a player reaches a certain level or XP threshold:

local Ranker = require(game.ServerScriptService:WaitForChild("CFRankBotController"))

local function applyRankReward(player, targetRankId)
    local success, result = Ranker.SetRankByUserId(player.UserId, targetRankId, "XP Reward")

    if success then
        print("XP reward rank applied to:", player.Name)
    else
        warn("Failed to apply XP reward rank:", result)
    end
end

-- Example usage:
-- applyRankReward(player, 10)

Error Handling

All module functions follow the same pattern: local success, data = Ranker.Function(...)

• If success == true: data is the full JSON response (e.g. data.message, data.data).
• If success == false: data is a human-readable error message.

local success, data = Ranker.Promote("ExampleUser", "Test Script")

if success then
    print("API OK:", data.message)
else
    warn("API error:", data)
end

Troubleshooting

• "HTTP request failed." – Ensure HTTP requests are enabled in Game Settings → Security.
• "Unauthorized: Invalid API key." – The key is wrong, expired, or not linked to your account/group.
• "Invalid JSON response." – Temporary server issue; try again or check the /status endpoint.
• Rank/permission errors from Roblox. – The bot account may not have permission, or the rank ID doesn’t exist in the group.
• No output at all. – Make sure the script requiring the module is a ServerScript and the path is correct.

Security Tips

• Never put your API key in a LocalScript or send it to the client.
• Keep CFRankBotController and CF_Config in server-side containers (e.g. ServerScriptService or ReplicatedStorage + server scripts).
• Only trusted server code should call Promote, Demote or SetRank.
• If you think your key has leaked, revoke it in the portal and generate a new one.