Events Overview

What Are Events?

Events represent friction points in your application where users might need help. Each event has:

Name: A unique identifier (e.g., checkout_abandoned, signup_stuck)
Label: A human-readable display name
Description: What this event represents
Prompt Template: Instructions for your agent with context placeholders

The Trigger Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Code     │────▶│  Trigger API    │────▶│   Your Agent    │
│                 │     │                 │     │                 │
│ trigger(event,  │     │ Builds message  │     │ Responds with   │
│   context)      │     │ from template   │     │ context         │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Your code detects a friction point and calls boostgpt.trigger()
The API finds the event, builds a message using the template and context
Your agent receives the message and generates a helpful response
The user sees the trigger UI, clicks, and starts a conversation

Context Variables

Context is the data you pass with each trigger. It gets injected into the prompt template.

// Your trigger call
boostgpt.trigger('checkout_abandoned', {
  cart_value: '$149.00',
  items_count: 3,
  user_name: 'Sarah'
});

// Your prompt template
A user named {{user_name}} abandoned checkout with {{items_count}} items
worth {{cart_value}}. Help them complete their purchase.

// Resulting message to agent
A user named Sarah abandoned checkout with 3 items worth $149.00.
Help them complete their purchase.

Auto-Created Events

If you trigger an event that doesn’t exist, it’s automatically created with:

Name: The event name you provided
Label: Auto-generated from name (e.g., checkout_abandoned → “Checkout Abandoned”)
Prompt Template: Default template that includes all context

This lets you start triggering immediately without pre-configuring events.

Event Properties

Property	Required	Description
`name`	Yes	Unique identifier (snake_case recommended)
`label`	No	Display name in dashboard
`description`	No	Notes about when/why this event triggers
`prompt_template`	No	Template with `{{variable}}` placeholders
`is_active`	No	Whether this event is enabled (default: true)

Plan Mode Progress Events

When using chat_mode: 'plan', the following progress events are emitted during processing:

Event	Description
`generating`	Plan synthesis started — the AI is preparing a polished plan response

These events only fire during plan mode requests. Once a plan is approved and execution begins, standard agent tool execution events are emitted instead.

Best Practices

Use descriptive event names

Names should clearly indicate the friction point:

✅ checkout_payment_failed
✅ onboarding_step3_stuck
❌ event1
❌ help_needed

Include relevant context

Pass information that helps your agent provide better assistance:

Current page or step
Error messages (if applicable)
User’s progress or history
Product/cart details

Write clear prompt templates

Templates should give your agent enough context to help immediately:

// Good template
User is stuck on the {{step_name}} step of onboarding.
They've been on this page for {{time_spent}} seconds.
Error shown (if any): {{error_message}}.
Help them proceed.

// Too vague
User needs help with {{step}}.

Event Lifecycle

Created: Event is defined in dashboard or auto-created on first trigger
Triggered: User hits friction point, your code calls boostgpt.trigger()
Logged: Trigger is recorded for analytics (timestamp, context, IP, etc.)
Chat Created: New conversation starts with context-aware first message
Resolved: User gets help, friction point addressed

Getting Started

Choose Your Path

Providers & Models

What Are Events?

The Trigger Flow

Context Variables

Auto-Created Events

Event Properties

Plan Mode Progress Events

Best Practices

Event Lifecycle

Next Steps

Creating Events

Prompt Templates

​What Are Events?

​The Trigger Flow

​Context Variables

​Auto-Created Events

​Event Properties

​Plan Mode Progress Events

​Best Practices

​Event Lifecycle

​Next Steps

Creating Events

Prompt Templates

What Are Events?

The Trigger Flow

Context Variables

Auto-Created Events

Event Properties

Plan Mode Progress Events

Best Practices

Event Lifecycle

Next Steps