Session ID Listeners

Overview

The Warmly Widget provides two new API methods that allow you to react when a session ID becomes available. These methods enable reliable integration with analytics platforms, third-party tools, and custom workflows that depend on Warmly's session ID. This session ID matches the one sent in the intent signal webhook.

API Methods

addSessionIdListener(callback)

Registers a callback function that will be invoked when the session ID becomes available.

Parameters:

• callback (Function, required): A function that receives the session ID as a string parameter

Returns:

• string: A unique listener ID that can be used to remove the listener later

Behavior:

• If the session ID already exists when you register the listener, your callback will be invoked immediately

• If the session ID doesn't exist yet, your callback will be invoked once when the session ID becomes available

• The listener is automatically removed after being invoked once

• Multiple listeners can be registered simultaneously, and all will be notified

Example Usage:

// Register a listener
const listenerId = warmly('addSessionIdListener', function(sessionId) {
  console.log('Session ID is now available:', sessionId);
  // Send to your analytics platform
  analytics.track('warmly_session_started', { sessionId });
  // Update your UI
  document.getElementById('session-info').textContent = sessionId;
});
console.log('Registered listener:', listenerId);

removeSessionIdListener(listenerId)

Removes a previously registered session ID listener before it has been invoked.

Parameters:

• listenerId (string, required): The listener ID returned by addSessionIdListener()

Returns:

• void

Behavior:

• Removes the listener from the internal registry

• If the listener has already been invoked, this method has no effect (listeners are auto-removed after invocation)

• Logs a warning if the listener ID doesn't exist

• Useful for cleanup when your component/page unmounts before the session ID is available

Example Usage:

// Register a listener
const listenerId = warmly('addSessionIdListener', function(sessionId) {
  console.log('Session ID:', sessionId);
});
// Later, if you need to cancel the listener before it fires
warmly('removeSessionIdListener', listenerId);