Discord API

Overview

The discordApi bridge provides a simple interface for interacting with the Discord REST API through an internal bot integration. It allows Ocean resources to manage:

• Guild information
• Discord members
• Roles
• Messages
• Bans
• Nicknames

The API automatically connects to the configured Discord guild when initialized and caches user data to reduce API calls.

Requirements

A Discord bot must be configured inside:

Private.Bot.token
Private.Bot.guildId
Private.Bot.channelId

The bot must have permissions for:

• Manage Roles
• Manage Messages
• Ban Members
• View Members
• Manage Nicknames

Export

discordApi

Ocean.discordApi()

Returns the initialized Discord API instance.

• Returns: discordApi

Discord API Class

---@class discordApi
---@field bot table
---@field users table

Functions

getGuild

discordApi:getGuild(callback)

Returns information about the configured Discord guild.

• callback: function(guild)
• Returns: nil

Example:

discordApi:getGuild(function(guild)
    print(guild.name)
end)

getDiscordUser

discordApi:getDiscordUser(discordId, callback)

Returns a guild member. Results are cached automatically.

• discordId: string
• callback: function(member)
• Returns: nil

Example:

discordApi:getDiscordUser("123456789", function(member)
    if member then
        print(member.user.username)
    end
end)

getRoles

discordApi:getRoles(callback)

Returns all guild roles.

• callback: function(roles)
• Returns: nil

userHasRole

discordApi:userHasRole(discordId, roleId, callback)

Checks if a Discord user has a specific role.

• discordId: string
• roleId: string
• callback: function(hasRole)
• Returns: nil

Example:

discordApi:userHasRole("123", "999", function(hasRole)
    if hasRole then
        print("User has role")
    end
end)

addRole

discordApi:addRole(discordId, roleId, callback)

Adds a role to a Discord user.

• discordId: string
• roleId: string
• callback: function(success)
• Returns: nil

removeRole

discordApi:removeRole(discordId, roleId, callback)

Removes a role from a Discord user.

• discordId: string
• roleId: string
• callback: function(success)
• Returns: nil

sendMessage

discordApi:sendMessage(channelId, content, callback)

Sends a message to a Discord channel.

• channelId: string (optional)
• content: string
• callback: function(message)
• Returns: nil

If no channel is provided, the default configured channel is used.

Example:

discordApi:sendMessage(nil, "Server restarted", function(message)
    print("Message sent")
end)

getMessages

discordApi:getMessages(channelId, limit, callback)

Returns recent messages from a channel.

• channelId: string (optional)
• limit: number (1–100)
• callback: function(messages)
• Returns: nil

Example:

discordApi:getMessages(nil, 25, function(messages)
    print(#messages)
end)

isUserBanned

discordApi:isUserBanned(discordId, callback)

Checks if a user is banned.

• discordId: string
• callback: function(banned, reason)
• Returns: nil

banUser

discordApi:banUser(discordId, deleteMessageDays, callback)

Bans a Discord user.

• discordId: string
• deleteMessageDays: number (0–7)
• callback: function(success)
• Returns: nil

Example:

discordApi:banUser("123", 1, function(success)
    if success then
        print("User banned")
    end
end)

unbanUser

discordApi:unbanUser(discordId, callback)

Removes a Discord ban.

• discordId: string
• callback: function(success)
• Returns: nil

setNickname

discordApi:setNickname(discordId, nickname, callback)

Changes a user's nickname.

• discordId: string
• nickname: string | nil
• callback: function(success)
• Returns: nil

Setting nickname to nil resets it.

Example:

discordApi:setNickname("123", "Ocean Player", function(success)
    print(success)
end)

invalidateCache

discordApi:invalidateCache(discordId)

Clears a cached Discord user so fresh data will be fetched on next request.

• discordId: string
• Returns: nil

Internal Behavior

The API automatically:

• Connects to the Discord guild on startup
• Caches member data
• Validates HTTP responses
• Logs connection status
• Handles API errors safely

Example

local discord = Ocean.discordApi()
 
discord:userHasRole("123456", "999999", function(hasRole)
    if hasRole then
        print("Player is whitelisted")
    end
end)
 
discord:sendMessage(nil, "Player joined the server")

Summary

Discord API provides:

• Discord guild integration
• Role management
• Messaging support
• Moderation tools
• User caching
• Bot based automation

Designed to be a lightweight internal bridge between Ocean resources and Discord.