Skip to main content
Event triggers let you show contextual messages above the chat widget bubble when specific events happen in your application — a user hits an error, completes onboarding, abandons checkout, etc. When the user clicks the trigger message, it fires the event to your agent and opens the resulting conversation in the widget.

​
Basic Usage

// Initialize the widget first
boostgpt.init({ botId: 'YOUR_BOT_UUID' });

// Fire a trigger when something happens
boostgpt.trigger('checkout_abandoned', {
  cart_value: '$49.99',
  items: 3
}, {
  text: 'Looks like you left some items behind. Need help?'
});
The trigger message appears as a card stacked above the widget bubble — same style as greeting messages.

​
Trigger Options

boostgpt.trigger(eventName, context, options);
ParameterTypeDescription
eventNamestringRequired. The event name (must match an event configured in your agent’s Events tab)
contextobjectKey-value pairs passed to the agent as conversation context
optionsobjectDisplay and behavior options (see below)

​
Options

OptionTypeDefaultDescription
textstringEvent nameThe message shown in the trigger card
delaynumber0Milliseconds to wait before showing the trigger
dismissiblebooleantrueWhether the user can close the trigger card
screenshotbooleanfalseCapture a screenshot of the page and send it with the trigger
userobjectnullUser metadata: { id, email, name, ...custom }

​
Screenshots

Enable screenshot capture to give your agent visual context about what the user was seeing: 
boostgpt.trigger('ui_error', {
  error: 'Payment form failed to load',
  page: '/checkout'
}, {
  text: 'Something went wrong. Click here for help.',
  screenshot: true
});
Screenshot capture requires html2canvas. Add it to your page:
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>

​
Dismissing Triggers

// Dismiss a specific trigger
boostgpt.dismiss('checkout_abandoned');

// Dismiss all active triggers
boostgpt.dismissAll();

​
Custom Messages

Use addMessage() to show cards without firing an event — useful for announcements, tips, or custom CTAs: 
var msg = boostgpt.addMessage('New feature: Try our AI assistant!', {
  onClick: function() { boostgpt.open(); },
  dismissible: true
});

// Later, remove it programmatically
msg.dismiss();

​
Trigger Events

Listen for trigger lifecycle events: 
boostgpt.on('trigger:shown', function(data) {
  console.log('Trigger shown:', data.event);
});

boostgpt.on('trigger:clicked', function(data) {
  console.log('Trigger clicked:', data.event);
});

boostgpt.on('trigger:success', function(data) {
  console.log('Chat opened:', data.data.chat_url);
});

boostgpt.on('trigger:error', function(data) {
  console.error('Trigger failed:', data.error);
});
EventDescription
trigger:shownTrigger card appeared above the bubble
trigger:clickedUser clicked a trigger card
trigger:loadingTrigger is being processed
trigger:successTrigger completed, chat opened
trigger:errorTrigger failed

​
Trigger-Only Mode

If you only want triggers without the persistent chat bubble, set widget: false: 
boostgpt.init({
  botId: 'YOUR_BOT_UUID',
  widget: false  // no floating bubble — only trigger cards
});

// Triggers still work
boostgpt.trigger('error_detected', { code: 500 }, {
  text: 'Something broke. Click to report.'
});

​
Migration from trigger.js

If you were using the standalone trigger.js script, migrate to the unified widget.js: 
<script src="https://embed.boostgpt.co/trigger.js"></script>
<script>
  boostgpt.init({ botId: 'uuid' });
  boostgpt.trigger('event', context, { type: 'toast', message: 'Need help?' });
</script>
Key changes:
  • Replace trigger.js with widget.js
  • Remove type: 'toast' (toast is now the only trigger style)
  • Use text instead of message for the trigger card text
  • boostgpt.triggerDirect() is now just boostgpt.trigger()
  • The old trigger.js still works with a deprecation warning but will be removed in a future version