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.

Get started

ADK

Studio

Integrations

Webchat

Desk

Creating a trigger

Naming a Trigger

Event structure

Multiple event subscriptions

Reference

Trigger props

Handler parameters

​Creating a trigger

​Naming a Trigger

​Event structure

​Multiple event subscriptions

​Reference

​Trigger props

​Handler parameters

Creating a trigger

Naming a Trigger

Event structure

Multiple event subscriptions

Reference

Trigger props

Handler parameters