JavaScript SDK

The DealerAI webchat widget exposes a window.DealerAI JavaScript API that lets you open, close, and send messages 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. Actions that affect the chat (open, send, etc.) should be called after the page has loaded.

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).

Full Integration Example

The following example shows a typical integration on a vehicle detail page where a custom Ask about this car button opens the chat in context with vehicle information:

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

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

<script>
  // 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.