Set up triggers

Triggers subscribe to events and run a handler when those events fire. Unlike conversations (which respond to user messages), triggers respond to system events, integration events, and custom events you define.

Creating a trigger

Create a file in src/triggers/:

import { Trigger } from '@botpress/runtime'

export default new Trigger({
  name: 'onConversationStarted',
  events: ['webchat:conversationStarted'],
  handler: async ({ event }) => {
    console.log('New conversation started:', event.payload)
  },
})

The events array lists which events this trigger subscribes to. The handler runs when any of the listed events fire.

Viewing triggers in the dev console

You can browse your triggers from the dev console at Components > Triggers:

Event format

Events use the format "integration:eventName" for integration events, or just the event name for custom events defined in agent.config.ts.

The handler receives a single event parameter:

To make API calls from a trigger, pull the client from the runtime context: const client = context.get("client").

Multiple events

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

export default new Trigger({
  name: 'onLinearIssue',
  description: 'Handle Linear issue events',
  events: ['linear:issueCreated', 'linear:issueUpdated', 'linear:issueDeleted'],
  handler: async ({ event }) => {
    if (event.type === 'linear:issueCreated') {
      // Handle new issue
    } else if (event.type === 'linear:issueUpdated') {
      // Handle update
    } else if (event.type === 'linear:issueDeleted') {
      // Handle deletion
    }
  },
})

Custom events

Triggers can subscribe to custom events you define in agent.config.ts:

export default defineConfig({
  events: {
    orderPlaced: {
      description: 'Fired when an order is placed',
      schema: z.object({
        orderId: z.string(),
        total: z.number(),
      }),
    },
  },
})

import { Trigger } from '@botpress/runtime'

export default new Trigger({
  name: 'onOrderPlaced',
  events: ['orderPlaced'],
  handler: async ({ event }) => {
    const { orderId, total } = event.payload
    // Process the order
  },
})

Using actions from triggers

Triggers can call actions for reusable logic:

import { Trigger, actions } from '@botpress/runtime'

export default new Trigger({
  name: 'onConversationStarted',
  events: ['webchat:conversationStarted'],
  handler: async ({ event }) => {
    if (event.payload.conversationId) {
      await actions.webchat.showWebchat({
        conversationId: event.payload.conversationId,
      })
    }
  },
})