All Docs
Navibot

Navibot - Utilities

Last modified

HTTP Client

Sends an HTTP GET request. Blocks until complete. Returns the response body as a string, or nil on error.

local body = navi.http.get("https://api.example.com/endpoint", nil)
if body then
    local data = navi.json.decode(body)
end
-- With custom headers
local body = navi.http.get("https://api.private.com/data", {
    ["Authorization"] = "Bearer " .. api_key,
    ["Accept"]        = "application/json"
})

navi.http.post(url, body, headers?)

Sends an HTTP POST request. Blocks until complete. Returns the response body as a string, or nil on error.

local response = navi.http.post(
    "https://api.example.com/submit",
    navi.json.encode({ key = "value" }),
    { ["Content-Type"] = "application/json" }
)

Important: Both http.get and http.post block the Lua thread while the request is in flight. For commands that make HTTP calls, always call ctx.defer() first.

JSON

Serializes a Lua table or value to a JSON string.

local data = { title = "Best pet?", options = { "Dog", "Cat" }, closed = false }
navi.db.set("polls:data:1", navi.json.encode(data))

Parses a JSON string into a Lua value (table, number, string, boolean, or nil).

local raw  = navi.db.get("polls:data:1")
local poll = raw and navi.json.decode(raw)
if poll then
    navi.log.info("Poll title: " .. poll.title)
end

JSON and the database together are the standard pattern for storing structured data (arrays, nested tables) since navi.db.set only accepts flat strings.

Permissions

The permissions system maps users and roles to a level hierarchy. Levels from lowest to highest: "user" → "helper" → "moderator" → "admin" → "owner". Permissions are configured from the TUI.

Checks whether the user meets or exceeds the required level. If they do not, it automatically sends them an ephemeral denial message and returns false. If they do, it returns true.

navi.create_slash("nuke", "Delete all posts", {}, function(ctx)
    if not navi.require_perm(ctx, "moderator") then return end
    -- Only reaches here if the user is a moderator, admin, or owner
end)

Like require_perm but silent — returns true or false with no side effects. Use when you want to adjust behavior based on permissions without sending a denial.

if navi.check_perm(ctx, "moderator") then
    -- Show extra fields to mods
end

Returns the user’s highest permission level as a string. Never returns nil; defaults to "user".

local level = navi.get_perm_level(ctx)
ctx.reply("Your permission level is: " .. level)