JavaScript SDK

The DealerAI webchat widget exposes a window.DealerAI JavaScript API that lets you open, close, send messages, and listen to events from your own website code.

Availability

The window.DealerAI object is created synchronously when the loader script is parsed — before the React bundle has finished downloading. You can start registering event listeners immediately after the script tag, but actions that affect the chat (open, send, etc.) should be called after the page has loaded.

<dealerai-chat data-dealer-id="YOUR_DEALER_ID"></dealerai-chat>
<script type="module" src="https://webchat.dealerai.com/webcomponent-loader.js"></script>

<script>
  // Register a listener as soon as the loader has run
  window.DealerAI.addListener('lead', function (data) {
    console.log('Lead captured', data);
  });
</script>

Methods

api(payload)

The primary method for sending commands to the widget.

window.DealerAI.api({ action: 'ACTION_NAME', data: { /* ... */ } });

Open the chat window

window.DealerAI.api({ action: 'openchat' });

Close the chat window

window.DealerAI.api({ action: 'closechat' });

Open the chat and send a message

When the customer clicks a custom button on your website (e.g., "Ask about this car"), you can open the chat and pre-send a message — including a VIN and an optional hint — so the AI immediately responds in context:

window.DealerAI.api({
  action: 'send',
  data: {
    vin: '1HGBH41JXMN109186',
    hint: 'The customer wants to know about financing options for this vehicle.',
  },
});

The data object is sent as metadata to the AI on webchat/join. Supported fields:

Reset the conversation

window.DealerAI.api({ action: 'reset' });

This ends the current DirectLine session, clears the message history, and starts fresh. Use this after a customer logs out or after a completed transaction.

load()

Initialise the widget. Only needed when you have set ?initialize=false on the script URL to defer widget startup.

window.DealerAI.load();

See Deferred initialisation for the full usage pattern.

unload()

Completely unmount the widget from the page and remove all event listeners.

window.DealerAI.unload();

Call window.DealerAI.load() to remount it. Useful for single-page applications that need to tear down and rebuild the widget when the current route changes significantly (e.g., when navigating from a public page to an authenticated portal).

addListener(event, callback)

Register a callback for a named widget event.

window.DealerAI.addListener('eventName', function (data) {
  // handle event
});

Only one listener per event name is supported. Calling addListener with the same event name a second time replaces the previous listener.

Available events

removeListener(event)

Remove a previously registered event listener.

window.DealerAI.removeListener('lead');

raiseEvent(event, payload)

Manually fire a registered listener. Useful for testing integrations without waiting for the real event to occur.

window.DealerAI.raiseEvent('lead', { conversationId: 'test-123' });

Full Integration Example

The following example shows a typical integration on a vehicle detail page:

1. The page passes the VIN and customer data to the widget via HTML attributes
2. A custom Ask about this car button is wired to open the chat in context
3. A lead event listener forwards captured leads to the dealership's CRM

<dealerai-chat
  data-dealer-id="YOUR_DEALER_ID"
  data-name="Jane Smith"
  data-email="jane@example.com">
</dealerai-chat>
<script type="module" src="https://webchat.dealerai.com/webcomponent-loader.js"></script>

<button id="ask-btn">Ask about this car</button>

<script>
  // Listen for leads and forward to CRM
  window.DealerAI.addListener('lead', function (data) {
    myCRM.submitLead({
      source: 'webchat',
      conversationId: data.conversationId,
    });
  });

  // Open chat in context when the button is clicked
  document.getElementById('ask-btn').addEventListener('click', function () {
    window.DealerAI.api({
      action: 'send',
      data: {
        vin: '1HGBH41JXMN109186', // replace with page VIN
        hint: 'Customer clicked "Ask about this car" on the VDP.',
      },
    });
  });
</script>

Analytics Events

The widget automatically tracks interactions and fires events to Google Analytics 4 (GA4) and ShiftDigital / ASC if configured. No extra code is required on your end.

To enable GA4 tracking, configure your GA4 Measurement ID under Settings → Webchat → Custom Tracking → GA4 ID.