Triggers

Triggers subscribe to events and execute handlers when those events occur. They enable your agent to respond to external events from integrations or system events.

Creating a trigger

Create a trigger in src/triggers/:

import { Trigger } from "@botpress/runtime";

export default new Trigger({
  name: "conversationStarted",
  events: ["webchat:conversationStarted"],
  handler: async ({ event }) => {
    // Trigger logic
  },
});

Triggers subscribe to events using an array of event names. The above Trigger only executes when it receives the webchat:conversationStarted event.

Naming a Trigger

Trigger names can contain only alphanumeric characters and underscores.

Event structure

The handler receives an event object with:

• event.type - The event type string (one of the subscribed events)
• event.payload - The event payload data (varies by event type)

You can read these properties to handle the event appropriately:

import { Trigger } from "@botpress/runtime";

export default new Trigger({
  name: "reactionAdded",
  description: "Handles WhatsApp reactions",
  events: ["whatsapp:reactionAdded"],
  handler: async ({ event }) => {
    // Handle WhatsApp reaction added event
    // event.type contains "whatsapp:reactionAdded"
    // event.payload contains information about the reaction
    const reactionData = event.payload;
    if (reactionData.reaction === "U+1F44D")
      // Process the reaction
  },
});

For reference information about the payload from integration events, check out the Integrations documentation.

Multiple event subscriptions

A trigger can subscribe to multiple events and handle each of them differently:

export default new Trigger({
  name: "onLinearIssueUpdate",
  description: "Handles Linear issue events",
  events: [
    "linear:issueCreated",
    "linear:issueDeleted",
    "linear:issueUpdated",
  ],
  handler: async ({ event }) => {
    // Check event type to handle different cases
    if (event.type === "linear:issueDeleted") {
      // Handle deletion
    } else if (event.type === "linear:issueCreated") {
      // Handle creation
    } else if (event.type === "linear:issueUpdated") {
      // Handle update
    }
  },
});

Reference

Trigger props

Show Trigger props

name · string · required

Unique name for the trigger. Must be at least 3 characters, less than 255 characters, and contain only alphanumeric characters and underscores.

description · string

Optional description of what the trigger does. Must be less than 1024 characters.

events · string[] · required

Array of event names to subscribe to. The trigger will execute when any of these events occur.

handler · (props: object) => Promise<void> | void · required

Handler function that processes the matched event. The props object structure is documented in the handler parameters section below.

Handler parameters

The handler function receives the matched event:

Show Handler parameters

event · object · required

The event object that matched one of the subscribed event names.

Show Event properties

type · string · required

The event type string (one of the subscribed events).

payload · any · required

The event payload data. The structure varies by event type—for integration events, check out the integration documentation.