KAL v2 language About 3 min read

KAL triggers & context

WHEN COMMAND, WHEN EVENT, WHEN INTERACTION and SCHEDULE — the complete event list and every context variable each trigger provides.

A trigger declares when a block of KAL runs. There are four kinds, and each provides a strictly-defined set of context variables — using a variable a trigger does not provide is a compile error (S007), which keeps event handlers honest.

WHEN COMMAND#

kal

KAL VERSION 2.0;
AUTOMATION announcement_command {

    WHEN COMMAND announce (text AS STRING) [permission: "ManageMessages"] {
        SEND MESSAGE text TO channel;
    }
}

The command name is a bare identifier (not quoted). Parameters are declared (name AS TYPE, …) and are bound from the invocation.
The optional [permission: "…"] clause is checked against the calling member; a missing permission answers with exactly which permission was needed.
Context: interaction, member, author, channel, guild, options, data, config.
options.<name> mirrors the parameters; member.mention mentions the caller.

WHEN EVENT#

kal

KAL VERSION 2.0;
AUTOMATION join_logger {

    CONFIG {
        log_channel: CHANNEL [
            label: "Log channel",
            description: "Where joins are announced",
            required: true
        ];
    }

    WHEN EVENT member_join {
        SEND MESSAGE "Welcome, " + member.mention + "!" TO config.log_channel;
    }
}

The complete event list with the context each provides:

Event	Context variables
`message_sent`, `message_create`	message, channel, member, author, guild, data, config
`message_deleted`	message, channel, guild, data, config
`message_edited`	message, old_message, channel, member, author, guild, data, config
`reaction_added`, `reaction_removed`	emoji, reaction_count, message, channel, member, guild, data, config
`member_join`, `member_leave`	member, guild, data, config — no `channel`
`button_clicked`	interaction, channel, member, guild, data, config
`channel_created`, `channel_deleted`	channel, guild, data, config
`channel_updated`	channel, old_channel, guild, data, config
`channel_pins_updated`	channel, guild, time, data, config
`role_created`, `role_deleted`	role, guild, data, config
`role_updated`	role, old_role, guild, data, config
`member_banned`	user, member, guild, reason, data, config
`member_unbanned`	user, guild, data, config
`thread_created`, `thread_deleted`	thread, channel, guild, data, config
`thread_updated`	thread, old_thread, channel, guild, data, config
`voice_state_updated`	member, channel, old_channel, guild, voice_state, old_voice_state, data, config

WHEN INTERACTION#

Fires when a component (button/select) with the matching custom id is clicked. Custom ids are matched exactly.

kal

KAL VERSION 2.0;
AUTOMATION verify_panel {

    WHEN INTERACTION verify_button {
        REPLY "You have verified your account!" EPHEMERAL;
    }
}

Context: interaction, member, author, channel, guild, data, config, message. Acknowledge slow work with DEFER INTERACTION first (see Actions).

SCHEDULE#

kal

KAL VERSION 2.0;
AUTOMATION hourly_digest {

    CONFIG {
        target: CHANNEL [
            label: "Digest channel",
            description: "Where the digest is posted",
            required: true
        ];
    }

    SCHEDULE EVERY 3600000 {
        SEND MESSAGE "Hourly digest" TO config.target;
    }
}

SCHEDULE EVERY <ms> repeats; SCHEDULE AFTER "<duration>" runs once. Duration strings accept minutes/hours spellings such as "10m", "1h".
Context is deliberately small: guild, data, config only. There is no member or channel — targets come from CONFIG.
Scheduled bodies belong at the top level of the AUTOMATION block, next to WHEN blocks.

data and config#

Every trigger provides data (the event payload for this run) and config (the server's values for this script's CONFIG fields).