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 chat interactions.

Registering event listeners

Pass event listeners to initializeAiChatSdk as the third parameter:

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

initializeAiChatSdk('your-zero-click-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.CHAT_CLOSED:
        // Handle chat closed
        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)

Available events

CHAT_SHOWN

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

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

Example:

case AiChatSdkEventType.CHAT_SHOWN:
  console.log('Chat opened with session ID:', event.data.chatSessionId);

  if (event.data.initialMessage) {
    console.log('Initial message:', event.data.initialMessage);
  }

  // Track in analytics
  analytics.track('chat_opened', {
    sessionId: event.data.chatSessionId,
    hasInitialMessage: !!event.data.initialMessage,
  });
  break;

When it fires:

When sdk.initializeChat() is called

CHAT_CLOSED

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

{
  chatSessionId: string;
}

Example:

case AiChatSdkEventType.CHAT_CLOSED:
  console.log('Chat closed');

  // Track in analytics
  analytics.track('chat_closed', {
    sessionId: event.data.chatSessionId,
  });
  break;

When it fires:

User clicks the close button on the chat panel

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;
}

Example:

case AiChatSdkEventType.CHAT_ERROR_SHOWN:
  console.error('Chat error shown for session:', event.data.chatSessionId);

  // Track that an error was shown
  analytics.track('chat_error_shown', {
    sessionId: event.data.chatSessionId,
  });
  break;

When it fires:

API request fails
Network error occurs
Invalid response from backend

This event indicates an error was displayed to the user, but does not include error details in the payload.

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
}

Example:

case AiChatSdkEventType.CHAT_LINK_CLICKED:
  console.log('User clicked link:', event.data.url);

  // Track link clicks
  analytics.track('chat_link_clicked', {
    sessionId: event.data.chatSessionId,
    url: event.data.url,
  });
  break;

When it fires:

User clicks a link in a chat message
User clicks an offer redirect URL

CHAT_MESSAGE_SENT

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

{
  chatSessionId: string;
}

Example:

case AiChatSdkEventType.CHAT_MESSAGE_SENT:
  console.log('User sent a message');

  // Track message sends
  analytics.track('chat_message_sent', {
    sessionId: event.data.chatSessionId,
  });
  break;

When it fires:

User types a message and presses send (message content not included)
After CHAT_PROMPT_CLICKED when user selects a prompt (fires in sequence after the prompt click event)

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

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
}

Example:

case AiChatSdkEventType.CHAT_PROMPT_CLICKED:
  console.log('User clicked prompt:', event.data.prompt);

  // Track specific prompt clicks
  analytics.track('chat_prompt_clicked', {
    sessionId: event.data.chatSessionId,
    prompt: event.data.prompt,
  });
  break;

When it fires:

User clicks one of the suggested prompts in the chat interface

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
}

Example:

case AiChatSdkEventType.CHAT_PROMPTS_SHOWN:
  console.log('Prompts shown:', event.data.prompts);

  // Track prompt impressions
  analytics.track('chat_prompts_shown', {
    sessionId: event.data.chatSessionId,
    promptCount: event.data.prompts.length,
    prompts: event.data.prompts,
  });
  break;

When it fires:

Chat interface displays suggested prompts to the user

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
}

Example:

case AiChatSdkEventType.CHAT_TOP_MERCHANTS_SHOWN:
  console.log('Top merchants shown:', event.data.merchants);

  // Track merchant impressions
  analytics.track('chat_merchants_shown', {
    sessionId: event.data.chatSessionId,
    merchantCount: event.data.merchants.length,
    merchants: event.data.merchants,
  });
  break;

When it fires:

AI displays a list of recommended merchants to the user

The merchants array contains strings (URLs or identifiers), not full merchant objects.

Event flow examples

Typical chat session flow

1. User opens chat
   ↓
2. CHAT_SHOWN
   - data: { chatSessionId: '...', initialMessage: 'Show me products' }
   ↓
3. CHAT_PROMPTS_SHOWN
   - data: { chatSessionId: '...', prompts: ['Show deals', 'Compare prices', ...] }
   ↓
4. User clicks a prompt
   ↓
5. CHAT_PROMPT_CLICKED
   - data: { chatSessionId: '...', prompt: 'Show deals' }
   ↓
6. CHAT_MESSAGE_SENT
   - data: { chatSessionId: '...' }
   ↓
7. AI responds with merchant recommendations
   ↓
8. CHAT_TOP_MERCHANTS_SHOWN
   - data: { chatSessionId: '...', merchants: ['https://amazon.com', ...] }
   ↓
9. User clicks a merchant link
   ↓
10. CHAT_LINK_CLICKED
    - data: { chatSessionId: '...', url: 'https://amazon.com' }
   ↓
11. User closes chat
   ↓
12. CHAT_CLOSED
    - data: { chatSessionId: '...' }

Error flow

1. User sends message
   ↓
2. CHAT_MESSAGE_SENT
   - data: { chatSessionId: '...' }
   ↓
3. API request fails
   ↓
4. CHAT_ERROR_SHOWN
   - data: { chatSessionId: '...' }

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-zero-click-api-key', {
  // ... config
}, [
  (event: AiChatSdkEvent) => {
    const baseProperties = {
      sessionId: event.data.chatSessionId,
      timestamp: Date.now(),
    };

    switch (event.type) {
      case AiChatSdkEventType.CHAT_SHOWN:
        sessionTimers.set(event.data.chatSessionId, Date.now());

        analytics.track('ai_chat_opened', {
          ...baseProperties,
          hasInitialMessage: !!event.data.initialMessage,
          initialMessage: 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,
          sessionDurationSeconds: Math.floor(duration / 1000),
        });

        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,
          domain: new URL(event.data.url).hostname,
        });
        break;

      case AiChatSdkEventType.CHAT_ERROR_SHOWN:
        analytics.track('ai_chat_error_shown', {
          ...baseProperties,
        });
        break;

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

      case AiChatSdkEventType.CHAT_PROMPTS_SHOWN:
        analytics.track('ai_chat_prompts_shown', {
          ...baseProperties,
          promptCount: event.data.prompts.length,
        });
        break;

      case AiChatSdkEventType.CHAT_TOP_MERCHANTS_SHOWN:
        analytics.track('ai_chat_merchants_shown', {
          ...baseProperties,
          merchantCount: event.data.merchants.length,
          merchants: event.data.merchants,
        });
        break;
    }
  }
]);

Debugging events

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

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

You can also add a simple debug listener:

initializeAiChatSdk('your-zero-click-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:

Engagement: CHAT_SHOWN → CHAT_MESSAGE_SENT → CHAT_CLOSED
Session duration: Time between CHAT_SHOWN and CHAT_CLOSED
Conversion funnel: CHAT_PROMPTS_SHOWN → CHAT_PROMPT_CLICKED → CHAT_LINK_CLICKED
Error monitoring: CHAT_ERROR_SHOWN frequency and types

2. Handle errors gracefully

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

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

3. Avoid blocking operations

Event handlers should be fast and non-blocking. Use async operations carefully:

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:
  // Clean up session data
  sessionTimers.delete(event.data.chatSessionId);
  sessionData.delete(event.data.chatSessionId);
  break;

5. Respect user privacy

Be mindful of what data you collect and track:

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;

Next steps

Configuration

Configure SDK features and behavior

Data providers

Integrate offer redirect URLs and cashback data

Troubleshooting

Common issues and solutions

AI Chat JS SDK Reference

​Overview

​Registering event listeners

​Event structure

​Available events

​CHAT_SHOWN

​CHAT_CLOSED

​CHAT_ERROR_SHOWN

​CHAT_LINK_CLICKED

​CHAT_MESSAGE_SENT

​CHAT_PROMPT_CLICKED

​CHAT_PROMPTS_SHOWN

​CHAT_TOP_MERCHANTS_SHOWN

​Event flow examples

​Typical chat session flow

​Error 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

​Next steps

Configuration

Data providers

Troubleshooting

Overview

Registering event listeners

Event structure

Available events

CHAT_SHOWN

CHAT_CLOSED

CHAT_ERROR_SHOWN

CHAT_LINK_CLICKED

CHAT_MESSAGE_SENT

CHAT_PROMPT_CLICKED

CHAT_PROMPTS_SHOWN

CHAT_TOP_MERCHANTS_SHOWN

Event flow examples

Typical chat session flow

Error 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

Next steps