Scripting Guide

Lesson 2: Events and Payloads

The 15 events agents can subscribe to, the exact payload shape each one delivers, and how to pick the right one.

One agent, one event

When you create an agent you bind it to exactly one event from a fixed list. The event determines two things: when your function runs and what the payload argument contains. Getting the payload shape right is most of the work of writing a correct agent.

The event catalog

Reading a payload

Payload objects are plain data snapshots with async action methods attached. For example, a guildMemberAdd payload:

export async function onJoin(payload) {
  // This event's payload has two top-level keys: member and guild.
  const { member, guild } = payload;

  // Plain data you can read directly:
  // member.id, member.displayName, member.user.username,
  // member.joinedTimestamp, member.roleIds, ...
  // guild.id, guild.name, guild.memberCount, ...

  // Async lookups go through the guild object:
  const channel = await guild.channels.fetch("123456789012345678");
  if (!channel || channel.error) return; // bad ID or missing access

  await channel.send(
    "Welcome " + member.displayName + "! You are member #" + guild.memberCount + "."
  );
}

Before-and-after events

messageUpdate and guildMemberUpdate deliver a before and an after so you can detect what changed. before is a plain snapshot (data only); after carries the action methods.

export async function onMemberUpdate({ before, after, guild }) {
  if (before.nickname === after.nickname) return; // something else changed

  const log = await guild.channels.fetch("123456789012345678");
  if (!log || log.error) return;

  await log.send(
    after.user.username + " changed nickname: " +
    (before.nickname ?? "(none)") + " -> " + (after.nickname ?? "(none)")
  );
}

Choosing the right event

• Want to respond to text people type? messageCreate.
• Want welcome flows or autoroles? guildMemberAdd.
• Want goodbye logs? guildMemberRemove.
• Want moderation logging? messageDelete, messageUpdate, guildBanAdd, guildMemberUpdate.
• Want reaction roles or starboards? messageReactionAdd and messageReactionRemove.
• Want clickable UI (buttons, menus, modals)? Build it from any event, handle it with interactionCreate (Lesson 7).

Common pitfalls

• Destructuring the wrong shape. const { member } = payload works on guildMemberAdd but is undefined on messageCreate, where the payload is the message itself.
• Expecting events that are not in the list. There is no voiceStateUpdate, no presenceUpdate, and no scheduled/timer event. If it is not in the table above, an agent cannot subscribe to it.
• Comparing `before` methods. before in update events is data only; call actions on after.
• Reacting to deletes with replies. On messageDelete the message is gone; you cannot reply to it. Send to a channel instead.

Exercise

Create a goodbye.js agent on guildMemberRemove that posts <username> left the server to a log channel of your choice. Then create a second agent on guildBanAdd that posts the ban reason (payload.reason may be null; print no reason given in that case).