Chat

Clerk offers a JavaScript interface for integrating Chat component into your application. Similar to the shopping cart API, the Chat API allows you to configure hooks for chat events and perform various actions through simple commands.

Chat Control Methods

Use these commands to manage Chat:

Method	Action	Parameters
`Clerk('chat', 'open')`	Opens Chat window.	None
`Clerk('chat', 'close')`	Closes Chat window.	None
`Clerk('chat', 'toggle')`	Toggles open/closing of Chat window.	None
`Clerk('chat', 'clear')`	Clears Chat (restarting the conversation).	None
`Clerk('chat', 'enable')`	Makes Chat component visible.	None
`Clerk('chat', 'disable')`	Hides Chat component.	None
`Clerk('chat', 'toast', text, emoji)`	Displays toast notification with supplied arguments.	`text`: string, `emoji`: string (optional)
`Clerk('chat', 'prompt_message', 'text')`	Updates the chats initial prompt to change its behaviour.	`text`: string
`Clerk('chat', 'user_message', text)`	Sends message as user.	`text`: string
`Clerk('chat', 'assistant_message', text)`	Sends message as assistant.	`text`: string
`Clerk('chat', 'metadata', payload)`	Updates metadata used by Chat to understand what the user is currently doing. Metadata can be freely defined.	`payload`: `{"current_page": {"page_id": "id_090292", "page_type": "product"}, "user_preferences": "Likes yellow and blue colors."}`
`Clerk('chat', 'on', <event_name>, callback)`	Listens to Chat events and adds a callback for specified event.	`<event_name>`: `message\open\enable\support`, `callback`: `fn`
`Clerk('chat', 'enlarge', value)`	Toggles Chat enlarge feature.	`value`: boolean (optional)

Chat Event Hooks & Data Structures

Configure chat behaviour with these event hooks. Each hook receives an event object with specific properties:

Clerk("config", {
  chat: {
    onReady: (e) => { 
      // Called when chat finishes initialization
      console.log("Chat initialized", e); 
    },
    onMessage: (e) => {
      // Triggered on new messages (both incoming and outgoing)
      console.log("New message:", e); 
    },
    onOpen: (e) => {
      // Fired when chat visibility changes
      console.log("Chat visibility:", e); 
    },
    onEnable: (e) => {
      // Called when chat gets hidden
      console.log("Chat hidden status:", e); 
    },
    onSupport: (e) => {
      // Called when Contact Support override is enabled, and user needs support.
      // Contains a summary of the conversation in the event details
      console.log("Chat support summary:", e);
    },
  }
});

Event Data Structures

`onReady` Event

{
  ready: boolean;  // Chat initialization status
}

`onMessage` Event

{
  message: {
    role: 'ai' | 'user' | 'results';  // Message origin
    text?: string;                    // Plain text content. For 'ai' and 'user' messages.
    html?: string;                    // Formatted HTML content. Contains product sliders sent by 'results' role.
  }
}

`onOpen` Event

{
  open: boolean;  // Current visibility state
}

`onEnable` Event

{
  enabled: boolean;  // Current enabled state
}

Updating event hooks

In addition to setting event hooks within the config function, you can dynamically update them. This allows for more flexibility when modifying chat behavior without requiring a full reconfiguration.

To register or update an event hook, use the following syntax:

Clerk('chat', 'on', '<event_name>', callback);

Where <event_name> is one of the supported event types:

message - Triggered when a new message is received.
hide - Fired when the Chat is fully hidden/revealed. (display)
show - Triggered when Chat is shown/hidden (component)
support - Triggered when the user needs support, and customer support function is overridden.

Implementation Example

Basic chat control button:

<button onclick="Clerk('chat', 'toggle')">
  Toggle Chat
</button>

Full configuration with message handling:

// Initialize Clerk with chat hooks
Clerk("config", {
  key: 'your-public-api-key',
  chat: {
    onMessage: (message) => {
      console.log('Received:', message);
      // Add custom message handling logic
    },
    onReady: (status) => {
      if(status.ready) {
        Clerk('chat', 'toast', 'Chat ready!', '🎉');
      }
    }
  }
});

Chat Control Methods

Chat Event Hooks & Data Structures

Event Data Structures

onReady Event

onMessage Event

onOpen Event

onEnable Event