/teams-app-developer

bolt-events-ts

purpose

Events API patterns for Slack Bolt.js — app.event() registration, event type payloads, retry handling, built-in event middleware (ignoreSelf, directMention), and event-vs-message handler selection.

rules

1. Use app.event(eventType, handler) for all non-message events. Register handlers with the event type string (e.g., "reaction_added", "member_joined_channel", "app_home_opened"). Bolt routes events by matching event.type. slack.dev/bolt-js/concepts/event-listening
2. Use app.message() for message events, not app.event("message"). app.message() provides text pattern matching (string/RegExp), say(), and subtype-aware filtering. app.event("message") works but lacks these conveniences. Bolt throws an error if you pass "message" with subtype patterns to app.event(). slack.dev/bolt-js/concepts/message-listening
3. Events do NOT have ack(). Unlike commands, actions, and views, event handlers receive no ack function. Bolt automatically acknowledges event webhooks with HTTP 200 before your handler runs. slack.dev/bolt-js/concepts/event-listening
4. say() is only available for events with channel context. Events like app_mention, message, and member_joined_channel include a channel, so say() works. Events like team_join or app_home_opened may not — use client.chat.postMessage() with an explicit channel. slack.dev/bolt-js/concepts/event-listening
5. ignoreSelf is enabled by default. Bolt filters out events generated by your own bot (matching bot_id for messages, user for other events). This prevents infinite loops. Disable with ignoreSelf: false in App constructor if you need to process your own events. slack.dev/bolt-js/concepts/event-listening
6. Use context.retryNum and context.retryReason to detect retries. Slack retries event delivery if your server doesn't respond with 200 in time. Check context.retryNum to skip duplicate processing or log retry attempts. api.slack.com/events-api#retries
7. Event type can be matched with RegExp. Pass a RegExp to app.event() for pattern matching: app.event(/^member_/, handler) matches both member_joined_channel and member_left_channel. Matches are stored in context.matches. slack.dev/bolt-js/concepts/event-listening
8. Subscribe to events in the Slack app dashboard. app.event() in code does nothing if the event type isn't enabled in "Event Subscriptions" in your app's configuration. Both code and dashboard must agree. api.slack.com/events-api#subscriptions
9. The body property contains the full event envelope. It includes team_id, api_app_id, event_id, event_time, and authorizations. The event property is just the inner event payload. Use body when you need workspace-level metadata. api.slack.com/events-api#event_type_structure
10. URL verification is handled automatically by Bolt receivers. Both HTTPReceiver and ExpressReceiver respond to { type: "url_verification" } challenges without any handler code. You don't need to implement this yourself. slack.dev/bolt-js/concepts/event-listening

patterns

Common event handlers

import { App } from "@slack/bolt";

const app = new App({
  token: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

// React to app mentions
app.event("app_mention", async ({ event, say }) => {
  await say(`Hey <@${event.user}>, you mentioned me!`);
});

// Welcome new team members
app.event("team_join", async ({ event, client }) => {
  // team_join has no channel context — use client directly
  await client.chat.postMessage({
    channel: "#general",
    text: `Welcome to the team, <@${event.user.id}>! :wave:`,
  });
});

// Track reactions
app.event("reaction_added", async ({ event, client }) => {
  if (event.reaction === "white_check_mark" && event.item.type === "message") {
    await client.chat.postMessage({
      channel: event.item.channel,
      thread_ts: event.item.ts,
      text: `<@${event.user}> marked this as done :white_check_mark:`,
    });
  }
});

// Update App Home when opened
app.event("app_home_opened", async ({ event, client }) => {
  if (event.tab !== "home") return;
  await client.views.publish({
    user_id: event.user,
    view: {
      type: "home",
      blocks: [
        {
          type: "section",
          text: { type: "mrkdwn", text: `*Welcome home, <@${event.user}>!*` },
        },
        { type: "divider" },
        {
          type: "section",
          text: { type: "mrkdwn", text: "Here's what you can do..." },
        },
      ],
    },
  });
});

// Channel membership changes (RegExp pattern)
app.event(/^member_(joined|left)_channel$/, async ({ event, say, context }) => {
  const action = context.matches?.[1]; // "joined" or "left"
  await say(`<@${event.user}> ${action} the channel.`);
});

Retry-aware event handler

app.event("app_mention", async ({ event, say, context }) => {
  // Skip retries to avoid duplicate processing
  if (context.retryNum !== undefined) {
    console.log(`Skipping retry #${context.retryNum}: ${context.retryReason}`);
    return;
  }

  // Process normally
  await say(`Got your mention, <@${event.user}>!`);
});

Event handler with listener middleware

import { App, directMention } from "@slack/bolt";

const app = new App({
  token: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

// Only fires when message starts with @bot mention
app.message(directMention(), async ({ message, say }) => {
  await say(`You said: ${(message as any).text}`);
});

// Custom listener middleware: only process DMs
const onlyDMs = async ({ event, next }: { event: any; next: () => Promise<void> }) => {
  if (event.channel_type === "im") {
    await next();
  }
};

app.event("message", onlyDMs, async ({ event, say }) => {
  await say?.("Got your DM!");
});

pitfalls

• Not subscribing in the dashboard: app.event("reaction_added") in code does nothing if reaction_added isn't enabled in "Event Subscriptions" in your Slack app settings. You'll see no errors — events just don't arrive.
• Using say() in events without channel context: team_join, tokens_revoked, app_uninstalled, and some other events don't have a channel. Calling say() throws "channel not found". Use client.chat.postMessage() with an explicit channel.
• Infinite loops from bot's own events: If you disable ignoreSelf and your handler posts a message that triggers the same event, you get an infinite loop. Always check event.bot_id or event.user against your bot's identity when ignoreSelf is off.
• Processing retries as new events: Slack retries after ~10 seconds, ~1 minute, and ~5 minutes if your server doesn't respond with 200 quickly. Without checking context.retryNum, you'll process the same event multiple times. Use idempotency keys or skip retries.
• Confusing event and body: The event property is the inner event payload. The body property wraps it with envelope metadata (team_id, event_id, etc.). Use event for the event data and body when you need workspace context.
• Missing scopes for events: Each event type requires specific OAuth scopes. For example, channels:history for public channel messages, im:history for DMs, reactions:read for reactions. Missing scopes cause silent failure — no events arrive.

references

• https://api.slack.com/events-api
• https://api.slack.com/events
• https://slack.dev/bolt-js/concepts/event-listening
• https://slack.dev/bolt-js/concepts/message-listening
• https://api.slack.com/scopes
• https://github.com/slackapi/bolt-js

instructions

This expert covers the Slack Events API integration in Bolt.js TypeScript. Use it when you need to: handle non-message events with app.event(); understand event payloads and the event envelope structure; implement retry-aware handlers; use built-in middleware like ignoreSelf and directMention; build App Home views with app_home_opened; track reactions, team joins, and channel membership changes; and understand the relationship between event subscriptions in the dashboard and handler registration in code. Pair with runtime.bolt-foundations-ts.md for general handler context and runtime.ack-rules-ts.md to understand why events don't have ack().

research

Deep Research prompt:

"Write a micro expert on the Slack Events API in Bolt.js TypeScript. Cover: app.event() registration (string and RegExp), common event types (app_mention, reaction_added, team_join, app_home_opened, member_joined/left_channel), event payload shapes, retry handling (context.retryNum, context.retryReason), built-in middleware (ignoreSelf, directMention), say() availability per event type, event envelope (body) vs inner event, URL verification auto-handling, and dashboard subscription requirements. Provide 2-3 canonical TypeScript examples."