Configuration

Each Discord server gets its own set of giveaway settings. Settings control defaults for new giveaways, enforce limits, and apply entry restrictions. They persist in Flashcore and survive restarts.

Settings can be managed three ways:

• Slash commands -- /giveaway settings get, /giveaway settings set, /giveaway settings reset
• Imperative API -- getGuildSettings() and setGuildSettings() exported from @robojs/giveaways
• REST API -- GET/PATCH /api/giveaways/:guildId/settings (requires @robojs/server)

When no custom settings have been saved for a guild, the plugin uses built-in defaults.

Settings reference

Defaults

Control the default values for new giveaways.

Limits

Set upper bounds on giveaway parameters.

Restrictions

Guild-wide entry restrictions applied to all giveaways. Individual giveaways can also set their own restrictions via the allow_roles, deny_roles, and min_account_age_days options on /giveaway start.

Managing settings with commands

View current settings:

/giveaway settings get

Update specific settings (only provided values change):

/giveaway settings set default_winners: 3 button_label: Join the Raffle dm_winners: false max_winners: 50

Reset everything to defaults:

/giveaway settings reset

All settings commands that modify data require Manage Server permission.

Managing settings with the API

The plugin exports two functions for programmatic access:

import { getGuildSettings, setGuildSettings } from '@robojs/giveaways'

import { getGuildSettings, setGuildSettings } from '@robojs/giveaways'

getGuildSettings(guildId)

Returns the current settings for a guild. If no custom settings exist, returns the built-in defaults.

const settings = await getGuildSettings('123456789012345678')
console.log(settings.defaults.winners) // 1
console.log(settings.limits.maxWinners) // 20

const settings = await getGuildSettings('123456789012345678')
console.log(settings.defaults.winners) // 1
console.log(settings.limits.maxWinners) // 20

setGuildSettings(guildId, settings)

Persists a complete settings object for the guild. This is a full overwrite, not a merge. Read first, modify, then write:

import { getGuildSettings, setGuildSettings } from '@robojs/giveaways'

const guildId = '123456789012345678'
const current = await getGuildSettings(guildId)

await setGuildSettings(guildId, {
  ...current,
  defaults: {
    ...current.defaults,
    winners: 3,
    buttonLabel: 'Join the Raffle'
  },
  limits: {
    ...current.limits,
    maxWinners: 50
  }
})

import { getGuildSettings, setGuildSettings } from '@robojs/giveaways'

const guildId = '123456789012345678'
const current = await getGuildSettings(guildId)

await setGuildSettings(guildId, {
  ...current,
  defaults: {
    ...current.defaults,
    winners: 3,
    buttonLabel: 'Join the Raffle'
  },
  limits: {
    ...current.limits,
    maxWinners: 50
  }
})

TypeScript types

Import types from either the main entry point or the ./types subpath:

import type { GuildSettings } from '@robojs/giveaways'
// or
import type { GuildSettings } from '@robojs/giveaways/types'

// or

The full GuildSettings interface:

interface GuildSettings {
  defaults: {
    winners: number
    duration: string
    buttonLabel: string
    dmWinners: boolean
  }
  limits: {
    maxWinners: number
    maxDurationDays: number
  }
  restrictions: {
    allowRoleIds: string[]
    denyRoleIds: string[]
    minAccountAgeDays: number | null
  }
}

Validation rules

When settings are updated via slash commands or the REST API, these validation rules apply:

The slash command validates a subset of these fields (the ones it accepts as options). The REST API validates all fields comprehensively.

Discord intents

The plugin requires these Discord gateway intents:

• Guilds
• GuildMessages

These are declared in the plugin's config and should be enabled automatically.

Next Steps