Update bot status

The framework provides a StatusManager that automatically cycles through your bot’s presence statuses. You configure it via your zumito.config.ts file, which is loaded by the framework’s launcher.

Setup

Create a status options file

Create src/config/StatusOptions.ts:

import { ActivityType } from "zumito-framework/discord";
import type { StatusManagerOptions } from "zumito-framework";

export const statusOptions: StatusManagerOptions = {
    statuses: [{
        status: 'online',
        activities: [{
            name: 'z-help',
            type: ActivityType.Playing
        }]
    }],
    RuledStatuses: [],
    updateInterval: 15000,
    order: "sequential"
};

Pass to zumito.config.ts

import type { LauncherConfig } from 'zumito-framework';
import { statusOptions } from './src/config/StatusOptions.js';

export const config: LauncherConfig = {
    statusOptions: statusOptions,
    // ... bundles, discordClientOptions, etc.
};

Configuration reference

`StatusManagerOptions`

Field	Type	Required	Description
`statuses`	`PresenceData[]`	Yes	List of statuses the bot cycles through.
`RuledStatuses`	`RuledPresenceData[]`	No	Time-conditional statuses (e.g., holiday-specific).
`updateInterval`	`number`	No	How often the bot changes status (ms). If omitted, cycles once on ready but does not repeat.
`order`	`"sequential" \| "random"`	No	Cycle order. Defaults to sequential.

`PresenceData` (per status entry)

Field	Type	Description
`status`	`'online' \| 'dnd' \| 'idle' \| 'invisible'`	Discord presence status.
`activities`	`ActivitiesOptions[]`	Array of activities to display.

An activity has:

Field	Type	Description
`name`	`string`	Text displayed (e.g., `Playing z-help`).
`type`	`ActivityType`	`ActivityType.Playing`, `ActivityType.Watching`, `ActivityType.Listening`, `ActivityType.Streaming`, `ActivityType.Competing`.

`RuledPresenceData` (time-based statuses)

Statuses with date rules — only active within a time range:

RuledStatuses: [{
    status: 'online',
    activities: [{
        name: 'Halloween event!',
        type: ActivityType.Playing
    }],
    rules: [{
        startTime: new Date('2026-10-25'),
        endTime: new Date('2026-11-01')
    }]
}]

Rule field	Type	Description
`startTime`	`Date`	Status becomes active after this date.
`endTime`	`Date`	Status becomes inactive after this date.

Examples

Multiple rotating statuses (sequential)

statuses: [
    {
        status: 'online',
        activities: [{ name: 'with fire', type: ActivityType.Playing }]
    },
    {
        status: 'dnd',
        activities: [{ name: 'the docs', type: ActivityType.Watching }]
    },
    {
        status: 'idle',
        activities: [{ name: 'lofi beats', type: ActivityType.Listening }]
    }
],
updateInterval: 20000,
order: "sequential"

The bot cycles through each status every 20 seconds, in order.

Random status cycling

order: "random",
updateInterval: 30000

The bot picks a random status from the list every 30 seconds.

Streaming status

statuses: [{
    status: 'online',
    activities: [{
        name: 'Coding with Zumito',
        type: ActivityType.Streaming,
        url: 'https://twitch.tv/yourchannel'
    }]
}]

Manual status updates

You can also update the status programmatically from your modules:

import { ServiceContainer } from 'zumito-framework';
import { ZumitoFramework } from 'zumito-framework';

const framework = ServiceContainer.get(ZumitoFramework);
framework.statusManager?.setStatus({
    status: 'dnd',
    activities: [{ name: 'maintenance...', type: ActivityType.Playing }]
});

Listening to status changes

The statusChanged event fires every time the presence changes:

framework.eventEmitter.on('statusChanged', (presenceData) => {
    console.log('Bot status changed to:', presenceData);
});

How it works under the hood

The launcher (node_modules/zumito-framework/dist/launcher.js) loads your zumito.config.ts.
It merges your config with framework defaults and passes it to ZumitoFramework.
During initialization, if statusOptions is defined, a StatusManager is created.
On the Discord ready event, the first status is set immediately.
If updateInterval is set, the status cycles on a timer.
RuledStatuses are filtered by their date rules — only active ones are included in the cycle.