Events - Sleek

Overview

The AI Chat SDK provides a comprehensive event system that notifies your application about user interactions and UI state changes. Events enable you to track user behavior, trigger analytics, and respond to interactions across the chat panel, badge, and inline input.

Registering event listeners

Pass event listeners to initializeAiChatSdk as the third parameter:

import {
  initializeAiChatSdk,
  AiChatSdkEventType,
  type AiChatSdkEvent,
} from '@sleek/ai-chat-sdk';

initializeAiChatSdk('your-api-key', {
  // ... options
}, [
  // Event listeners
  (event: AiChatSdkEvent) => {
    console.log('Event type:', event.type);
    console.log('Event data:', event.data);

    switch (event.type) {
      case AiChatSdkEventType.CHAT_SHOWN:
        // Handle chat opened
        break;
      case AiChatSdkEventType.BADGE_CLICKED:
        // Handle badge clicked
        break;
      // ... handle other events
    }
  }
]);

You can register multiple listeners, and all will be called when an event occurs.

Event structure

All events follow this structure:

interface AiChatSdkEvent {
  type: AiChatSdkEventType;
  data: {
    chatSessionId: string;
    // Additional properties vary by event type
  };
}

type: The event type (see available events below)
data: Event-specific data
chatSessionId: Unique identifier for the current chat session (present in all events)

Badge events

Events emitted by the floating badge entry point.

BADGE_SHOWN

Emitted when the badge becomes visible. Event type: AiChatSdkEventType.BADGE_SHOWN Payload:

{
  chatSessionId: string;
  prompts: string[];  // Array of prompts displayed on the badge
}

Example:

case AiChatSdkEventType.BADGE_SHOWN:
  analytics.track('badge_shown', {
    sessionId: event.data.chatSessionId,
    promptCount: event.data.prompts.length,
    prompts: event.data.prompts,
  });
  break;

BADGE_CLICKED

Emitted when the user clicks the badge. Event type: AiChatSdkEventType.BADGE_CLICKED Payload:

{
  chatSessionId: string;
}

Example:

case AiChatSdkEventType.BADGE_CLICKED:
  analytics.track('badge_clicked', {
    sessionId: event.data.chatSessionId,
  });
  break;

BADGE_CLOSED

Emitted when the badge is closed or hidden. Event type: AiChatSdkEventType.BADGE_CLOSED Payload:

{
  chatSessionId: string;
}

BADGE_PROMPT_CLICKED

Emitted when the user clicks a prompt on the badge. Event type: AiChatSdkEventType.BADGE_PROMPT_CLICKED Payload:

{
  chatSessionId: string;
  prompt: string;  // The prompt text that was clicked
}

Example:

case AiChatSdkEventType.BADGE_PROMPT_CLICKED:
  analytics.track('badge_prompt_clicked', {
    sessionId: event.data.chatSessionId,
    prompt: event.data.prompt,
  });
  break;

Inline events

Events emitted by the inline input entry point.

INLINE_SHOWN

Emitted when the inline input becomes visible. Event type: AiChatSdkEventType.INLINE_SHOWN Payload:

{
  chatSessionId: string;
  prompts: string[];  // Array of prompts displayed
}

INLINE_CLICKED

Emitted when the user clicks the inline input. Event type: AiChatSdkEventType.INLINE_CLICKED Payload:

{
  chatSessionId: string;
}

INLINE_PROMPT_CLICKED

Emitted when the user clicks a prompt in the inline input. Event type: AiChatSdkEventType.INLINE_PROMPT_CLICKED Payload:

{
  chatSessionId: string;
  prompt: string;  // The prompt text that was clicked
}

Chat events

Events emitted by the chat panel.

CHAT_SHOWN

Emitted when the chat panel becomes visible. Event type: AiChatSdkEventType.CHAT_SHOWN Payload:

{
  chatSessionId: string;
  initialMessage?: string;  // Optional initial message when chat was opened
}

Example:

case AiChatSdkEventType.CHAT_SHOWN:
  analytics.track('chat_opened', {
    sessionId: event.data.chatSessionId,
    hasInitialMessage: !!event.data.initialMessage,
  });
  break;

CHAT_CLOSED

Emitted when the user closes the chat panel. Event type: AiChatSdkEventType.CHAT_CLOSED Payload:

{
  chatSessionId: string;
}

CHAT_MESSAGE_SENT

Emitted when the user sends a message in the chat. Event type: AiChatSdkEventType.CHAT_MESSAGE_SENT Payload:

{
  chatSessionId: string;
}

For privacy reasons, the message content is not included in the event payload. Use this event to track engagement metrics like message frequency.

CHAT_PROMPTS_SHOWN

Emitted when suggested prompts are displayed to the user. Event type: AiChatSdkEventType.CHAT_PROMPTS_SHOWN Payload:

{
  chatSessionId: string;
  prompts: string[];  // Array of prompt suggestions shown
}

CHAT_PROMPT_CLICKED

Emitted when a user clicks a suggested prompt. Event type: AiChatSdkEventType.CHAT_PROMPT_CLICKED Payload:

{
  chatSessionId: string;
  prompt: string;  // The prompt text that was clicked
}

CHAT_LINK_CLICKED

Emitted when a user clicks a link within the chat interface. Event type: AiChatSdkEventType.CHAT_LINK_CLICKED Payload:

{
  chatSessionId: string;
  url: string;           // The URL that was clicked
  merchantName?: string; // Merchant name if available
  merchantUrl?: string;  // Merchant base URL if available
}

Example:

case AiChatSdkEventType.CHAT_LINK_CLICKED:
  analytics.track('chat_link_clicked', {
    sessionId: event.data.chatSessionId,
    url: event.data.url,
    merchantName: event.data.merchantName,
  });
  break;

CHAT_ERROR_SHOWN

Emitted when an error is displayed to the user in the chat interface. Event type: AiChatSdkEventType.CHAT_ERROR_SHOWN Payload:

{
  chatSessionId: string;
}

CHAT_TOP_MERCHANTS_SHOWN

Emitted when a list of top merchants is displayed in the chat. Event type: AiChatSdkEventType.CHAT_TOP_MERCHANTS_SHOWN Payload:

{
  chatSessionId: string;
  merchants: string[];  // Array of merchant URLs or identifiers
}

CHAT_TOP_MERCHANTS_CLICKED

Emitted when a user clicks on a merchant in the top merchants list. Event type: AiChatSdkEventType.CHAT_TOP_MERCHANTS_CLICKED Payload:

{
  chatSessionId: string;
  url: string;           // The URL that was clicked
  merchantName?: string; // Merchant name if available
  merchantUrl?: string;  // Merchant base URL if available
}

CHAT_PRODUCTS_SHOWN

Emitted when products are displayed in the chat. Event type: AiChatSdkEventType.CHAT_PRODUCTS_SHOWN Payload:

{
  chatSessionId: string;
}

CHAT_PRODUCTS_CLICKED

Emitted when a user clicks on a product. Event type: AiChatSdkEventType.CHAT_PRODUCTS_CLICKED Payload:

{
  chatSessionId: string;
  url: string;           // The product URL that was clicked
  merchantName?: string; // Merchant name if available
  merchantUrl?: string;  // Merchant base URL if available
}

CHAT_PRODUCTS_PAGE_NEXT_CLICKED

Emitted when the user clicks to view the next page of products. Event type: AiChatSdkEventType.CHAT_PRODUCTS_PAGE_NEXT_CLICKED Payload:

{
  chatSessionId: string;
}

CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED

Emitted when the user clicks to view the previous page of products. Event type: AiChatSdkEventType.CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED Payload:

{
  chatSessionId: string;
}

Event types reference

All available event types:

enum AiChatSdkEventType {
  // Badge events
  BADGE_CLICKED = 'BADGE_CLICKED',
  BADGE_SHOWN = 'BADGE_SHOWN',
  BADGE_CLOSED = 'BADGE_CLOSED',
  BADGE_PROMPT_CLICKED = 'BADGE_PROMPT_CLICKED',

  // Inline events
  INLINE_CLICKED = 'INLINE_CLICKED',
  INLINE_SHOWN = 'INLINE_SHOWN',
  INLINE_PROMPT_CLICKED = 'INLINE_PROMPT_CLICKED',

  // Chat events
  CHAT_SHOWN = 'CHAT_SHOWN',
  CHAT_CLOSED = 'CHAT_CLOSED',
  CHAT_ERROR_SHOWN = 'CHAT_ERROR_SHOWN',
  CHAT_LINK_CLICKED = 'CHAT_LINK_CLICKED',
  CHAT_MESSAGE_SENT = 'CHAT_MESSAGE_SENT',
  CHAT_PROMPT_CLICKED = 'CHAT_PROMPT_CLICKED',
  CHAT_PROMPTS_SHOWN = 'CHAT_PROMPTS_SHOWN',
  CHAT_TOP_MERCHANTS_SHOWN = 'CHAT_TOP_MERCHANTS_SHOWN',
  CHAT_TOP_MERCHANTS_CLICKED = 'CHAT_TOP_MERCHANTS_CLICKED',
  CHAT_PRODUCTS_CLICKED = 'CHAT_PRODUCTS_CLICKED',
  CHAT_PRODUCTS_PAGE_NEXT_CLICKED = 'CHAT_PRODUCTS_PAGE_NEXT_CLICKED',
  CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED = 'CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED',
  CHAT_PRODUCTS_SHOWN = 'CHAT_PRODUCTS_SHOWN',
}

Event flow examples

Badge to chat flow

1. User sees badge
   ↓
2. BADGE_SHOWN
   - data: { chatSessionId: '...', prompts: ['Find deals', ...] }
   ↓
3. User clicks a prompt on badge
   ↓
4. BADGE_PROMPT_CLICKED
   - data: { chatSessionId: '...', prompt: 'Find deals' }
   ↓
5. Chat panel opens
   ↓
6. CHAT_SHOWN
   - data: { chatSessionId: '...', initialMessage: 'Find deals' }
   ↓
7. AI responds with merchant recommendations
   ↓
8. CHAT_TOP_MERCHANTS_SHOWN
   - data: { chatSessionId: '...', merchants: ['https://amazon.com', ...] }

Product browsing flow

1. User asks about products
   ↓
2. CHAT_MESSAGE_SENT
   - data: { chatSessionId: '...' }
   ↓
3. AI responds with products
   ↓
4. CHAT_PRODUCTS_SHOWN
   - data: { chatSessionId: '...' }
   ↓
5. User clicks next page
   ↓
6. CHAT_PRODUCTS_PAGE_NEXT_CLICKED
   - data: { chatSessionId: '...' }
   ↓
7. User clicks a product
   ↓
8. CHAT_PRODUCTS_CLICKED
   - data: { chatSessionId: '...', url: '...', merchantName: 'Amazon' }

Analytics integration example

Here’s a complete example of integrating SDK events with an analytics service:

import {
  initializeAiChatSdk,
  AiChatSdkEventType,
  type AiChatSdkEvent,
} from '@sleek/ai-chat-sdk';

// Track session durations
const sessionTimers = new Map<string, number>();

// Initialize SDK with event listener
initializeAiChatSdk('your-api-key', {
  // ... config
}, [
  (event: AiChatSdkEvent) => {
    const baseProperties = {
      sessionId: event.data.chatSessionId,
      timestamp: Date.now(),
    };

    switch (event.type) {
      // Badge events
      case AiChatSdkEventType.BADGE_SHOWN:
        analytics.track('ai_badge_shown', {
          ...baseProperties,
          promptCount: event.data.prompts.length,
        });
        break;

      case AiChatSdkEventType.BADGE_CLICKED:
        analytics.track('ai_badge_clicked', baseProperties);
        break;

      case AiChatSdkEventType.BADGE_PROMPT_CLICKED:
        analytics.track('ai_badge_prompt_clicked', {
          ...baseProperties,
          prompt: event.data.prompt,
        });
        break;

      // Inline events
      case AiChatSdkEventType.INLINE_SHOWN:
        analytics.track('ai_inline_shown', {
          ...baseProperties,
          promptCount: event.data.prompts.length,
        });
        break;

      case AiChatSdkEventType.INLINE_PROMPT_CLICKED:
        analytics.track('ai_inline_prompt_clicked', {
          ...baseProperties,
          prompt: event.data.prompt,
        });
        break;

      // Chat events
      case AiChatSdkEventType.CHAT_SHOWN:
        sessionTimers.set(event.data.chatSessionId, Date.now());
        analytics.track('ai_chat_opened', {
          ...baseProperties,
          hasInitialMessage: !!event.data.initialMessage,
        });
        break;

      case AiChatSdkEventType.CHAT_CLOSED:
        const startTime = sessionTimers.get(event.data.chatSessionId);
        const duration = startTime ? Date.now() - startTime : 0;
        analytics.track('ai_chat_closed', {
          ...baseProperties,
          sessionDurationMs: duration,
        });
        sessionTimers.delete(event.data.chatSessionId);
        break;

      case AiChatSdkEventType.CHAT_MESSAGE_SENT:
        analytics.track('ai_chat_message_sent', baseProperties);
        break;

      case AiChatSdkEventType.CHAT_LINK_CLICKED:
        analytics.track('ai_chat_link_clicked', {
          ...baseProperties,
          url: event.data.url,
          merchantName: event.data.merchantName,
        });
        break;

      case AiChatSdkEventType.CHAT_TOP_MERCHANTS_CLICKED:
        analytics.track('ai_merchant_clicked', {
          ...baseProperties,
          url: event.data.url,
          merchantName: event.data.merchantName,
        });
        break;

      case AiChatSdkEventType.CHAT_PRODUCTS_CLICKED:
        analytics.track('ai_product_clicked', {
          ...baseProperties,
          url: event.data.url,
          merchantName: event.data.merchantName,
        });
        break;

      case AiChatSdkEventType.CHAT_ERROR_SHOWN:
        analytics.track('ai_chat_error', baseProperties);
        break;
    }
  }
]);

Debugging events

Enable debug mode to see all events logged to the console:

initializeAiChatSdk('your-api-key', {
  enableDebug: true,  // Enable debug logging
  // ... other options
});

You can also add a simple debug listener:

initializeAiChatSdk('your-api-key', {
  // ... config
}, [
  (event) => {
    console.group(`SDK Event: ${event.type}`);
    console.log('Data:', event.data);
    console.log('Session ID:', event.data.chatSessionId);
    console.groupEnd();
  }
]);

Best practices

1. Track meaningful metrics

Focus on events that provide business value:

Entry point engagement: BADGE_SHOWN → BADGE_CLICKED → CHAT_SHOWN
Conversion funnel: CHAT_PROMPTS_SHOWN → CHAT_PROMPT_CLICKED → CHAT_PRODUCTS_CLICKED
Session duration: Time between CHAT_SHOWN and CHAT_CLOSED
Error monitoring: CHAT_ERROR_SHOWN frequency

2. Handle errors gracefully

Wrap event handlers in try-catch to prevent one handler from breaking others:

initializeAiChatSdk('your-api-key', {}, [
  (event) => {
    try {
      handleEvent(event);
    } catch (error) {
      console.error('Error handling SDK event:', error);
    }
  }
]);

3. Avoid blocking operations

Event handlers should be fast and non-blocking:

initializeAiChatSdk('your-api-key', {}, [
  (event) => {
    // Good: Fire and forget
    analytics.track(event.type, event.data);

    // Avoid: Blocking async operation
    // await someSlowOperation();
  }
]);

4. Clean up resources

Use events to manage resources like timers:

case AiChatSdkEventType.CHAT_CLOSED:
  sessionTimers.delete(event.data.chatSessionId);
  sessionData.delete(event.data.chatSessionId);
  break;

5. Respect user privacy

Be mindful of what data you collect:

case AiChatSdkEventType.CHAT_MESSAGE_SENT:
  // Good: Track that a message was sent
  analytics.track('message_sent', {
    sessionId: event.data.chatSessionId,
  });

  // Note: Message content is not included in the event payload
  // This protects user privacy by default
  break;

​Overview

​Registering event listeners

​Event structure

​Badge events

​BADGE_SHOWN

​BADGE_CLICKED

​BADGE_CLOSED

​BADGE_PROMPT_CLICKED

​Inline events

​INLINE_SHOWN

​INLINE_CLICKED

​INLINE_PROMPT_CLICKED

​Chat events

​CHAT_SHOWN

​CHAT_CLOSED

​CHAT_MESSAGE_SENT

​CHAT_PROMPTS_SHOWN

​CHAT_PROMPT_CLICKED

​CHAT_LINK_CLICKED

​CHAT_ERROR_SHOWN

​CHAT_TOP_MERCHANTS_SHOWN

​CHAT_TOP_MERCHANTS_CLICKED

​CHAT_PRODUCTS_SHOWN

​CHAT_PRODUCTS_CLICKED

​CHAT_PRODUCTS_PAGE_NEXT_CLICKED

​CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED

​Event types reference

​Event flow examples

​Badge to chat flow

​Product browsing flow

​Analytics integration example

​Debugging events

​Best practices

​1. Track meaningful metrics

​2. Handle errors gracefully

​3. Avoid blocking operations

​4. Clean up resources

​5. Respect user privacy

Overview

Registering event listeners

Event structure

Badge events

BADGE_SHOWN

BADGE_CLICKED

BADGE_CLOSED

BADGE_PROMPT_CLICKED

Inline events

INLINE_SHOWN

INLINE_CLICKED

INLINE_PROMPT_CLICKED

Chat events

CHAT_SHOWN

CHAT_CLOSED

CHAT_MESSAGE_SENT

CHAT_PROMPTS_SHOWN

CHAT_PROMPT_CLICKED

CHAT_LINK_CLICKED

CHAT_ERROR_SHOWN

CHAT_TOP_MERCHANTS_SHOWN

CHAT_TOP_MERCHANTS_CLICKED

CHAT_PRODUCTS_SHOWN

CHAT_PRODUCTS_CLICKED

CHAT_PRODUCTS_PAGE_NEXT_CLICKED

CHAT_PRODUCTS_PAGE_PREVIOUS_CLICKED

Event types reference

Event flow examples

Badge to chat flow

Product browsing flow

Analytics integration example

Debugging events

Best practices

1. Track meaningful metrics

2. Handle errors gracefully

3. Avoid blocking operations

4. Clean up resources

5. Respect user privacy