Discord Module

Discord API integration for duso. Provides webhooks and Gateway client for real-time event handling.

Usage

discord = require("discord")

Functions

post_webhook(url, payload)

Post a message to a Discord webhook.

Parameters:

url (string) - Webhook URL from Discord
payload (object or string) - Message payload (content, embeds, etc.) or plain text string

Returns: Boolean (true if successful)

Example:

discord.post_webhook("https://discordapp.com/api/webhooks/...", {
  content = "Hello from Duso!"
})

session(config)

Create a Gateway client connection for real-time events.

Parameters:

config (object) - Configuration:
- token (string, required) - Discord bot token
- intents (number, optional) - Gateway intents (default: guilds + guild_messages + message_content)

Returns: Session object

Example:

bot = discord.session({
  token = env("DISCORD_TOKEN")
})

Gateway Intents

Intents control what events your bot receives. Combine intent constants with +:

discord = require("discord")

// Use individual intents
intents = discord.intents.guilds + discord.intents.guild_messages + discord.intents.message_content

bot = discord.session({
  token = env("DISCORD_TOKEN"),
  intents = intents
})

Available intents:

guilds (1)
guild_members (2)
guild_bans (4)
guild_emojis_and_stickers (8)
guild_integrations (16)
guild_webhooks (32)
guild_invites (64)
guild_voice_states (128)
guild_presences (256)
guild_messages (512)
guild_message_reactions (1024)
guild_message_typing (2048)
direct_messages (4096)
direct_message_reactions (8192)
direct_message_typing (16384)
message_content (32768)
guild_scheduled_events (65536)
auto_moderation_rules (1048576)
auto_moderation_execution (2097152)

Session Object

Returned by session(). Handles Gateway connection and event reading.

Methods

read([timeout]) - Block until an event arrives. Returns event object with type, data, and seq fields, or nil on timeout.
heartbeat() - Manually send a heartbeat (usually automatic).
send_message(channel_id, payload) - Send a message to a channel via the REST API.
is_connected() - Check if connection is still open.
close() - Close the connection.

Event Structure

Events returned by read() have this structure:

// Example event structure
event = {
  type = "MESSAGE_CREATE",
  data = {content = "hello", author = {id = 123}},
  seq = 1234
}

Common event types:

READY - Bot has authenticated and is ready
GUILD_CREATE - Guild information received
MESSAGE_CREATE - New message in a channel
MESSAGE_UPDATE - Message was edited
MESSAGE_DELETE - Message was deleted
INTERACTION_CREATE - Slash command or button interaction

Example: Echo Bot

discord = require("discord")

bot = discord.session({
  token = env("DISCORD_TOKEN"),
  intents = discord.intents.guilds + discord.intents.guild_messages + discord.intents.message_content
})

print("Bot connected")

while bot.is_connected() do
  event = bot.read(timeout=30)
  
  if event == nil then
    continue
  end

  if event.type == "MESSAGE_CREATE" then
    msg = event.data
    
    // Don't respond to bot messages
    if msg.author.bot then
      continue
    end

    // Don't respond to messages in DMs
    if msg.guild_id == nil then
      continue
    end

    // Send reply
    bot.send_message(msg.channel_id, {
      content = "You said: " + msg.content
    })
  end
end

bot.close()

Example: Webhook Alert

discord = require("discord")

webhook_url = "https://discordapp.com/api/webhooks/..."

discord.post_webhook(webhook_url, {
  content = "Alert: Server CPU at 90%",
  embeds = [
    {
      title = "System Alert",
      color = 16711680,  // Red
      fields = [
        {
          name = "Status",
          value = "Critical",
          inline = true
        },
        {
          name = "Timestamp",
          value = format_time(now()),
          inline = true
        }
      ]
    }
  ]
})

Notes

Bot token should be stored in environment variables (e.g., env("DISCORD_TOKEN"))
Webhook URLs can be posted to without authentication
Gateway requires a valid bot token and appropriate intents
Heartbeat is handled automatically by the client
For best performance, use the Gateway for real-time interaction and webhooks for simple notifications
Discord API enforces rate limits; consider adding delays between rapid requests