Skip to main content

​
Global Object

The script creates a global window.boostgpt object with the following methods:

​
Methods

​
init(config)

Initialize the trigger script with your agent configuration. 
boostgpt.init({
  botId: 'your-agent-uuid'
});
Parameters:
NameTypeRequiredDescription
configobjectYesConfiguration object
config.botIdstringYesYour agent’s UUID
Returns: void

​
trigger(eventName, context, options)

Trigger an event and display the trigger UI. 
boostgpt.trigger('checkout_help', {
  cart_value: '$149'
}, {
  type: 'toast',
  message: 'Need help?'
});
Parameters:
NameTypeRequiredDescription
eventNamestringYesEvent identifier
contextobjectNoData to pass to your agent
optionsobjectNoDisplay and behavior options
Returns: void Context Object: Any key-value pairs you want to pass to your agent. These are injected into prompt templates. 
{
  cart_value: '$149',
  items_count: 3,
  user_name: 'Sarah',
  current_page: '/checkout',
  // ... any custom data
}
Options Object: See Configuration for full options reference.

​
dismiss(eventName)

Remove a specific trigger from the page. 
boostgpt.dismiss('checkout_help');
Parameters:
NameTypeRequiredDescription
eventNamestringYesEvent identifier to dismiss
Returns: void

​
dismissAll()

Remove all active triggers from the page. 
boostgpt.dismissAll();
Parameters: None Returns: void

​
isLoaded()

Check if the trigger script is initialized. 
if (boostgpt.isLoaded()) {
  boostgpt.trigger('help', {});
}
Parameters: None Returns: boolean

​
Events

The trigger script dispatches custom events on the document:

​
boostgpt:trigger:shown

Fired when a trigger UI is displayed. 
document.addEventListener('boostgpt:trigger:shown', function(e) {
  console.log('Trigger shown:', e.detail.eventName);
});
Event Detail: 
{
  eventName: 'checkout_help',
  options: { ... }
}

​
boostgpt:trigger:clicked

Fired when a user clicks the trigger UI. 
document.addEventListener('boostgpt:trigger:clicked', function(e) {
  console.log('Trigger clicked:', e.detail.eventName);
  // Track in analytics
  analytics.track('Trigger Clicked', { event: e.detail.eventName });
});
Event Detail: 
{
  eventName: 'checkout_help',
  context: { ... }
}

​
boostgpt:trigger:dismissed

Fired when a trigger is dismissed (by user or programmatically). 
document.addEventListener('boostgpt:trigger:dismissed', function(e) {
  console.log('Trigger dismissed:', e.detail.eventName);
});
Event Detail: 
{
  eventName: 'checkout_help',
  reason: 'user' | 'programmatic'
}

​
boostgpt:chat:started

Fired when a chat is successfully created after clicking trigger. 
document.addEventListener('boostgpt:chat:started', function(e) {
  console.log('Chat started:', e.detail.chatUrl);
});
Event Detail: 
{
  eventName: 'checkout_help',
  chatId: 'chat-uuid',
  chatUrl: 'https://app.boostgpt.co/chat/...'
}

​
HTTP API

When users click triggers, the script calls:

​
POST /v1/bot/trigger

Creates a new chat with context. Request: 
{
  "bot_id": "agent-uuid",
  "event": "checkout_help",
  "context": {
    "cart_value": "$149"
  },
  "source_url": "https://example.com/checkout",
  "user": {
    "id": "user_123",
    "email": "user@example.com"
  },
  "screenshot": "data:image/jpeg;base64,..."  // Optional - base64 screenshot
}
Response (Success): 
{
  "success": true,
  "chat_id": "chat-uuid",
  "chat_url": "https://app.boostgpt.co/chat/agent-uuid/chat-uuid"
}
Response (Error): 
{
  "success": false,
  "error": "Bot not found",
  "code": "BOT_NOT_FOUND"
}
Error Codes:
CodeHTTP StatusDescription
BOT_NOT_FOUND404Agent doesn’t exist or is inactive
RATE_LIMITED429IP rate limit exceeded
PLAN_LIMIT_EXCEEDED402Monthly trigger limit reached
INVALID_REQUEST400Missing required fields

​
TypeScript Types

interface BoostGPTConfig {
  botId: string;
}

interface TriggerContext {
  [key: string]: string | number | boolean | object;
}

interface TriggerOptions {
  // Common
  type?: 'button' | 'toast' | 'banner' | 'inline';
  botId?: string;
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'top' | 'bottom';
  delay?: number;
  openInNewTab?: boolean;
  loadingText?: string;
  zIndex?: number;
  dismissible?: boolean;
  autoShow?: boolean;
  offsetX?: string;
  offsetY?: string;
  user?: UserData;

  // Screenshot
  captureScreenshot?: boolean;
  screenshotQuality?: number;
  screenshotMaxWidth?: number;
  screenshotMaxHeight?: number;

  // Button
  buttonText?: string;
  buttonColor?: string;
  textColor?: string;
  showIcon?: boolean;
  borderRadius?: string;
  fontSize?: string;
  fontWeight?: string;
  padding?: string;
  boxShadow?: string;

  // Toast
  message?: string;
  messages?: string[];
  avatar?: string;
  title?: string;
  toastBackground?: string;
  toastTextColor?: string;

  // Banner
  bannerText?: string;
  bannerColor?: string;
  bannerTextColor?: string;
  bannerPadding?: string;

  // Inline
  container?: string | HTMLElement;
}

interface UserData {
  id?: string;
  email?: string;
  name?: string;
  [key: string]: string | undefined;
}

interface BoostGPT {
  init(config: BoostGPTConfig): void;
  trigger(eventName: string, context?: TriggerContext, options?: TriggerOptions): void;
  dismiss(eventName: string): void;
  dismissAll(): void;
  isLoaded(): boolean;
}

declare global {
  interface Window {
    boostgpt: BoostGPT;
  }
}

​
Next Steps

Configuration

Options reference with examples

Best Practices

Tips for effective triggers