# DealerAI Documentation (/docs)
Welcome to the DealerAI documentation. This site covers every section of the DealerAI management
portal and how to use it effectively.
Where to Start [#where-to-start]
What is DealerAI? [#what-is-dealerai]
DealerAI is a conversational AI platform built for automotive dealerships. It automates customer
communication across multiple channels — including SMS, email, webchat, voice, Facebook, Instagram,
and Google Chat — providing intelligent, context-aware responses on behalf of your dealership.
The **DealerAI Reach** feature handles lead enquiries that arrive from dealership websites or
third-party listing sites like AutoTrader.com, routing responses through the most appropriate
channel automatically.
# API Reference (/docs/api)
The DealerAI API is a REST API that lets you integrate with the DealerAI platform programmatically.
All endpoints are under the `/api/v1/` prefix and require **Basic Authentication**.
Authentication [#authentication]
Every request must include an `Authorization` header using HTTP Basic Authentication:
```
Authorization: Basic
```
Use the [/api/v1/authentication/verify](/docs/api/api/v1/authentication/verify/post) endpoint to validate credentials and retrieve your `dealer_id`.
Base URL [#base-url]
| Environment | Base URL |
| ----------- | --------------------------------- |
| Production | `https://engine.dealerai.com` |
| Staging | `https://engine-stg.dealerai.dev` |
| Dev | `https://engine-dev.dealerai.dev` |
Endpoint Groups [#endpoint-groups]
# Getting Started (/docs/getting-started)
This guide covers the two most important areas to set up before you start using DealerAI:
your **General Settings** (dealership profile and channels) and **Reach** (automated customer
outreach). Getting these right first ensures the AI introduces your dealership correctly and
follows up with leads automatically from day one.
Start by signing in to the DealerAI portal at **[https://portal.dealerai.com](https://portal.dealerai.com)**.
Step 1 — Configure General Settings [#step-1--configure-general-settings]
Navigate to **Settings** in the sidebar and select your dealership. See the full [Settings guide](/docs/portal/settings) for a reference to every option.
Dealership Profile [#dealership-profile]
Fill in your dealership's core details under the **General Info** tab. The AI uses this
information when customers ask basic questions like your address, phone number, or website.
| Field | What to enter |
| ------------------- | ---------------------------------------------------------- |
| **Dealership name** | The name as you want it spoken to customers |
| **Website URL** | Your main dealership website |
| **Logo** | Upload your dealership logo (used in webchat and emails) |
| **Primary contact** | Main switchboard phone and general enquiries email |
| **Address** | Full street address |
| **Timezone** | Your local timezone — important for appointment scheduling |
Business Hours [#business-hours]
Under the **Hours** tab, set the opening and closing times for each department:
* **Sales** hours
* **Service** hours
* **Parts** hours
For each day, either set a time range or mark the day as closed. The AI will only offer
appointment slots within these hours and will inform customers of your hours when asked.
Set up your hours before enabling appointment booking in your AI agents — the AI needs
accurate hours to offer valid time slots to customers.
Activate Your Channels [#activate-your-channels]
Under the **Activation & Features** tab, enable the channels your dealership will use:
| Channel | When to enable |
| ----------- | ----------------------------------------------------------- |
| **Webchat** | You have the widget embedded (or plan to) on your website |
| **SMS** | You want to send and receive text messages with customers |
| **Email** | You want to handle customer email enquiries |
| **Voice** | You want the AI to answer and make phone calls |
| **Reach** | You want automated follow-up and re-engagement (see Step 2) |
Only enable channels that are fully configured. Channels that are enabled but not fully set up
may result in customers receiving no response.
Webchat Appearance [#webchat-appearance]
If you're using webchat, configure its look under the **Webchat** tab:
| Setting | Recommendation |
| -------------------- | ----------------------------------------------------------- |
| **Widget title** | Use your dealership name or "Chat with us" |
| **Greeting message** | A friendly opening (e.g., "Hi! How can we help you today?") |
| **Primary colour** | Match your dealership's brand colour |
| **Position** | Bottom-right is the industry standard |
Use **[Preview](/docs/portal/preview)** to test the widget appearance before going live. To embed the widget on your website, see the [Webchat Installation guide](/docs/webchat/installation).
***
Step 2 — Configure Reach [#step-2--configure-reach]
Navigate to **Reach** in the sidebar and select your dealership. See the full [Reach guide](/docs/portal/reach) for a reference to every option.
Reach automates your lead follow-up and re-engagement so no enquiry goes unanswered — even
outside of business hours.
Enable Reach [#enable-reach]
Open the **General Configuration** tab and confirm:
| Setting | Recommended value |
| -------------------- | ------------------------------------------ |
| **Reach enabled** | On |
| **Default channel** | SMS (higher open rates than email) |
| **Opt-out handling** | Respect all opt-outs immediately |
| **Timezone** | Match the timezone set in General Settings |
Set Up a Follow-Up Sequence [#set-up-a-follow-up-sequence]
A Follow-Up sequence automatically messages new leads who haven't responded after initial
contact. This is the most impactful sequence to configure first.
Go to
**Reach → Follow-Up**
Click
**Add Step**
for the first follow-up message
Set a delay of
**1 day**
after the initial contact
Write a short, friendly message checking in (e.g., "Hi
{"{{first_name}}"}
, just following up on your enquiry — happy to answer any questions!")
Add a second step with a
**3 day**
delay as a final nudge
Click
**Save**
Keep follow-up messages brief and conversational. Customers are more likely to respond to a
natural message than a formal sales pitch.
Configure Lead Routing [#configure-lead-routing]
Under **Forward Leads**, assign incoming leads from different sources to the correct AI agent:
* Leads from AutoTrader or Cars.com → **Sales Agent**
* Service form submissions → **Service Agent**
This ensures every lead is handled by an agent that knows how to respond to that type of enquiry.
Set a Fall-Through Action [#set-a-fall-through-action]
Under **Fall-Through**, configure what happens to leads that complete all sequences without a
response. A recommended starting point:
* Send a closing message: "We'll be here whenever you're ready — feel free to reach out any time."
* Flag the contact for manual review
***
What's Next [#whats-next]
Once Settings and Reach are configured, continue setting up the rest of your dealership:
# Integrations (/docs/integrations)
The Integrations section lets you connect DealerAI to the external systems your dealership
already uses — CRMs, inventory platforms, and scheduling tools — so data flows automatically
between them without manual re-entry.
Overview [#overview]
DealerAI supports two types of integrations:
| Type | Description |
| ----------------------- | ----------------------------------------------------------------------------- |
| **Integration Agents** | Pre-built connections to specific automotive platforms and CRMs |
| **Event Subscriptions** | Webhooks that notify external systems when specific events happen in DealerAI |
Navigate to **Integrations** in the sidebar to access both.
Integration Agents [#integration-agents]
Integration Agents are pre-configured connectors for popular automotive platforms. Enabling an
agent activates the two-way data sync between DealerAI and that platform.
Supported Platforms [#supported-platforms]
| Platform | Capabilities |
| ---------------- | ----------------------------------------------------------------------- |
| **VinSolutions** | Push leads and appointments into the VinSolutions CRM |
| **DealerSocket** | Sync lead data and appointment details with DealerSocket |
| **Fortellis** | Access automotive data services and inventory via the Fortellis network |
| **XTime** | Sync service appointments with XTime scheduling |
Contact your DealerAI account manager to enable additional integration agents not listed here.
Availability may depend on your subscription plan.
Configuring an Integration Agent [#configuring-an-integration-agent]
Go to
**Integrations → Integration Agents**
Find the platform you want to connect and click
**Configure**
Enter the required credentials (API key, dealer ID, or OAuth details) from your external platform account
Click
**Save and Test**
to verify the connection is working
Toggle the integration
**Active**
to begin data sync
Event Subscriptions (Webhooks) [#event-subscriptions-webhooks]
Event Subscriptions let you receive real-time notifications in your own systems whenever
something happens in DealerAI. This is useful for building custom integrations or triggering
workflows in tools like Zapier or your internal platforms.
Available Events [#available-events]
| Event | Triggered when |
| ---------------------- | ------------------------------------- |
| `conversation.started` | A new conversation begins |
| `appointment.created` | An appointment is booked by the AI |
| `appointment.updated` | An appointment is modified |
| `lead.created` | A new lead is received |
| `enrollment.completed` | A customer completes a Reach sequence |
Creating a Webhook [#creating-a-webhook]
Go to
**Integrations → Event Subscriptions**
Click
**Add Subscription**
Enter the
**Endpoint URL**
— the URL DealerAI will POST event data to
Select the
**Events**
you want to subscribe to
Click
**Save**
— DealerAI will immediately start sending events to your endpoint
Webhook endpoints must be HTTPS and publicly accessible. DealerAI will retry failed deliveries
up to three times before marking a delivery as failed.
# Portal Guide (/docs/portal)
The DealerAI portal is the central management interface for your dealership's AI-powered
communication system. From here you configure your AI agents, monitor live conversations,
manage your vehicle inventory, track leads and appointments, and review performance analytics.
You can access the live portal at **[https://portal.dealerai.com](https://portal.dealerai.com)**.
What is DealerAI? [#what-is-dealerai]
DealerAI is a conversational AI platform built for automotive dealerships. It automates customer
communication across multiple channels — SMS, email, webchat, voice, Facebook, Instagram, and
Google Chat — providing intelligent, context-aware responses on behalf of your dealership.
Key capabilities [#key-capabilities]
| Capability | Description |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Live conversations** | Monitor and join AI-led chats in real time across all channels |
| **Automated outreach** | Follow up with leads and re-engage past customers automatically via SMS and email |
| **AI agents** | Specialist agents for Sales, Service, Test Drive, Parts, Lease Return, and Trade-In |
| **Lead & ADF processing** | Automatically respond to leads from AutoTrader, Cars.com, and your website |
| **Appointment booking** | AI books Sales, Service, and Test Drive appointments and adds them to your calendar |
| **Inventory awareness** | The AI knows your current stock and answers detailed vehicle questions |
Channels [#channels]
DealerAI handles inbound and outbound communication across:
| Channel | Direction |
| ------------------------- | ------------------ |
| WebChat (embedded widget) | Inbound |
| SMS | Inbound & Outbound |
| Email | Inbound & Outbound |
| Voice (phone calls) | Inbound & Outbound |
| Facebook Messenger | Inbound |
| Instagram DMs | Inbound |
| Google Chat | Inbound |
Portal Sections [#portal-sections]
Access and Roles [#access-and-roles]
Access to portal sections depends on your assigned role:
| Role | Access level |
| ------------- | ------------------------------------------------------------------------ |
| **Admin** | Full access including organization management, billing, and all settings |
| **Org Admin** | Access across all stores within an organization |
| **User** | Day-to-day features: conversations, leads, inventory, appointments |
If you cannot see a section described in this guide, contact your organization administrator to
review your role permissions.
# Action Buttons (/docs/webchat/action-buttons)
Action buttons are pre-defined quick-reply shortcuts shown to customers on the webchat welcome
screen before they start typing. They let customers jump directly into a topic — such as
scheduling a service appointment or browsing inventory — with a single tap.
How Action Buttons Work [#how-action-buttons-work]
When a customer clicks an action button, the widget sends a message to the AI on their behalf.
The button can either:
* **Send a message** — The bot receives the text and continues the conversation as if the
customer had typed it themselves
* **Trigger an API event** — An event is dispatched to your website JavaScript for custom handling
The AI then responds in the same way it would to any customer message.
Configuring Action Buttons [#configuring-action-buttons]
Action buttons are managed in the DealerAI portal under **Settings → Webchat → Action Buttons**.
You can add, reorder, and remove buttons without touching any website code.
Each button has two required fields:
| Field | Description |
| ----------- | ----------------------------------------------------------- |
| **Title** | The label displayed on the button (e.g., "Book a Service") |
| **Message** | The text sent to the AI when the customer clicks the button |
Example configuration [#example-configuration]
| Title | Message sent to AI |
| -------------------- | ----------------------------------------------- |
| Book a Service | I'd like to book a service appointment |
| Browse Inventory | Show me your available vehicles |
| Get a Trade-In Value | What's my car worth? |
| Contact Sales | I'd like to speak to someone about buying a car |
Dynamic Action Buttons via Active Messages [#dynamic-action-buttons-via-active-messages]
If you have configured [Active Messages](/docs/portal/active-messages), the action buttons
shown in the welcome screen can be overridden by the matching active message rule. This lets
you tailor the button set to the page the customer is currently browsing.
For example, when a customer is on a vehicle detail page:
* **Default buttons**: Browse Inventory, Book a Service, Contact Sales
* **Active message override buttons**: More about this vehicle, Test Drive, Finance Calculator
Active messages are evaluated in real time when the widget loads, so the correct buttons
appear automatically without any extra code.
Action Button API Events [#action-button-api-events]
For advanced use cases, a button can dispatch a custom API event to your JavaScript instead
of (or in addition to) sending a message:
```json
{
"title": "Get a Quote",
"api": {
"event": "api.event",
"payload": {
"message": "price-enquiry-clicked"
}
}
}
```
Your website can listen for this event using the [`window.DealerAI.addListener`](/docs/webchat/sdk#addlistener) SDK method:
```javascript
window.DealerAI.addListener('price-enquiry-clicked', function (data) {
// Open your own quote form, track the click, etc.
myQuoteModal.open();
});
```
Appearance [#appearance]
Action buttons appear as pill-shaped tap targets in the welcome screen, below the welcome
message. They inherit the widget's primary accent colour for their border and text on the
light theme, and switch to white text on the dark theme.
On mobile, buttons stack vertically for easier tapping. On desktop, they flow horizontally and
wrap to multiple rows when needed.
There is no hard limit on the number of action buttons, but we recommend no more than
**5–6 buttons** to avoid overwhelming customers. Too many choices can reduce engagement.
DDC Chat Buttons [#ddc-chat-buttons]
If your website is powered by a DDC (Digital Dealer) platform, DealerAI can inject a native
**Chat Now** button directly into DDC vehicle listing cards. When a customer clicks this button,
the webchat widget opens and automatically sends the relevant VIN and an optional hint message
to the AI.
This integration is configured under **Settings → Webchat → Custom Features → DDC Chat Button**.
You can customise the button label and the hint message sent to the AI when the button is clicked.
DDC chat button integration requires the DDC API Loader to be present on the page.
It is provided automatically by your DDC-powered website.
# Configuration (/docs/webchat/configuration)
Widget configuration is managed in the DealerAI portal under **Settings → Webchat**. Changes
take effect immediately — no redeployment or code changes on your website are required.
Appearance [#appearance]
| Setting | Description |
| -------------------- | ------------------------------------------------------------------ |
| **Widget title** | Text shown at the top of the chat window (e.g., "Chat with us") |
| **Greeting message** | The first message customers see when they open the widget |
| **Primary colour** | The accent colour matching your dealership's branding |
| **Position** | Where the widget appears on the page — bottom-right or bottom-left |
| **Offline message** | Text shown to customers when outside of business hours |
| **Logo** | Upload a dealership logo shown in the chat header |
| **Avatar** | Upload a custom avatar for bot messages |
Use [Preview](/docs/portal/preview) in the portal to see how your widget looks with the
current settings before your customers see it.
Window Style [#window-style]
The widget supports three visual styles, configurable under **Settings → Webchat**:
| Style | Description |
| -------------- | ------------------------------------------------------------------------ |
| `window` | A traditional rectangular chat window pinned to the corner of the screen |
| `roundbox` | A rounded, card-style window — similar to `window` but with softer edges |
| `speechbubble` | A speech bubble that floats above a compact chat head icon |
All three styles support the same feature set. The style is also automatically forced to
`window` when the widget is used in [expand mode](/docs/webchat/installation#example-with-expand-mode).
Dark Mode [#dark-mode]
The widget ships with both a **light** and a **dark** theme. Customers can toggle between them
using the theme button in the chat header. The active theme selection is persisted in a cookie
so it is remembered across sessions.
You can set the default theme mode under **Settings → Webchat → Theme**.
Enabling the Webchat Channel [#enabling-the-webchat-channel]
The Webchat channel must be active for the widget to respond to visitors. To enable it:
Go to
**Settings**
in the portal sidebar and select your dealership
Open the
**Activation & Features**
tab
Toggle
**Webchat**
to enabled
Save your changes
If Webchat is disabled, the widget will still appear on your website but will display an
offline message instead of starting a live chat session.
Business Hours [#business-hours]
The AI uses the hours configured under **Settings → Hours** to determine when the webchat
is considered available. Outside of these hours, customers see the offline message.
Configure separate availability for:
* **Sales** hours
* **Service** hours
* **Parts** hours
For one-off closures, add dates in the [Holidays](/docs/portal/holidays) section.
Widget Behaviour [#widget-behaviour]
Language Support [#language-support]
The widget automatically detects the visitor's browser language and responds in that language
if it is supported. The default fallback language is English. Supported languages can be
restricted under **Settings → Webchat → Supported Languages**.
VIN Detection [#vin-detection]
If a visitor is browsing a specific vehicle page on your website, the widget automatically
detects the Vehicle Identification Number (VIN) from the page and passes it to the AI. This
allows the AI to answer questions about that specific vehicle without the customer having to
specify it.
The widget integrates with the DDC (Digital Dealer Communications) API for VIN detection on
DealerSocket-powered websites. On other platforms, VIN detection uses URL and meta tag parsing.
Session Persistence [#session-persistence]
Chat sessions persist across page navigation. If a customer starts a conversation on one
page and navigates to another, the conversation continues uninterrupted. Session state is
stored in browser cookies scoped to the dealer ID, with a 7-day TTL.
Idle Timeout [#idle-timeout]
If a customer is inactive for a configurable period, a countdown dialog appears asking whether
they want to continue or reset the conversation. The idle time threshold is set under
**Settings → Webchat → Idle Time**.
Private Mode [#private-mode]
When **Private Mode** is enabled, the widget only opens for visitors who have been passed
a valid user context via the `data-override-private` attribute in combination with pre-filled
user attributes. This is useful for authenticated portals where you only want to allow chat
for verified customers.
URL Allow / Block Lists [#url-allow--block-lists]
You can restrict which pages of your website show the widget:
* **Allow list** — Only show the widget on URLs that match the specified patterns
* **Block list** — Show the widget everywhere except URLs that match the specified patterns
Configure these lists under **Settings → Webchat → URL Restrictions**.
SMS Handoff [#sms-handoff]
When the SMS channel is configured and enabled, a **Text Us** button appears in the chat
header, allowing customers to switch from webchat to SMS. This is particularly useful when
a customer needs to leave the website but still wants to continue the conversation.
Enable this under **Settings → Webchat → Show SMS Button**.
# Customization (/docs/webchat/customization)
Beyond the standard portal settings, the DealerAI webchat widget exposes several advanced
customization mechanisms for developers and designers who need precise control over the
widget's look and feel.
Branding Colours [#branding-colours]
The widget's primary accent colour is set in the portal under **Settings → Webchat → Primary
Colour**. This colour applies to:
* The chat head button background
* The send button
* Action button borders and highlights
* The typing indicator
The accent colour is delivered to the widget via the API configuration and applied at runtime,
so no rebuild or redeployment is needed when you change it.
Theme Mode [#theme-mode]
The widget supports **light** and **dark** themes. Each theme defines a complete set of CSS
custom properties (variables) that control every colour in the UI.
| Variable | Light | Dark | Description |
| -------------------------------------------------- | --------- | --------- | ----------------------------- |
| `--theme-webchat-welcome-background-color` | `#ffffff` | `#212121` | Welcome screen background |
| `--theme-webchat-welcome-message-background-color` | `#ececed` | `#2e2e2e` | Bot message bubble background |
| `--theme-webchat-welcome-message-color` | `#000000` | `#ffffff` | Bot message text colour |
| `--theme-chat-window-header-background-color` | `#ffffff` | `#212121` | Chat window header background |
| `--theme-dialog-background-color` | `#fff` | `#212121` | Modal dialog background |
| `--theme-buy-window-background-color` | `#ffffff` | `#212121` | Payment window background |
The default theme can be configured under **Settings → Webchat → Default Theme Mode**.
Individual customers can toggle their preferred theme using the theme button in the chat
header — their choice is remembered via cookie.
Window Styles [#window-styles]
Three visual window styles are available:
`speechbubble` [#speechbubble]
A compact, speech-bubble-style welcome panel that floats above the chat head. Well-suited
for sites where you want a minimal footprint. The customer clicks the bubble or the chat head
to open the full chat window.
`window` [#window]
A traditional rectangular chat window anchored to the bottom corner. This is the most familiar
pattern and works well on most dealership websites.
`roundbox` [#roundbox]
Similar to `window` but with rounded corners and a card-style shadow. Gives a more modern,
softer feel.
Set the window style under **Settings → Webchat → Window Style**.
When the widget is used in [expand mode](/docs/webchat/installation#example-with-expand-mode),
the window style is automatically forced to `window` regardless of the portal setting.
Custom Inner CSS [#custom-inner-css]
For fine-grained styling adjustments, you can inject custom CSS into the widget via the portal
under **Settings → Webchat → Custom CSS**. This CSS is injected into the page `` and can
override widget-specific CSS custom properties.
Changing the accent colour dynamically [#changing-the-accent-colour-dynamically]
```css
/* Override accent on a specific page */
dealerai-chat .theme-light {
--theme-webchat-welcome-message-background-color: #f0f4ff;
--theme-webchat-welcome-message-color: #1a1a2e;
}
```
Adjusting chat window dimensions [#adjusting-chat-window-dimensions]
```css
/* Taller chat window on desktop */
@media (min-width: 768px) {
dealerai-chat .dealerai-chat-window {
height: 680px;
width: 400px;
}
}
```
Hiding the send button label [#hiding-the-send-button-label]
```css
dealerai-chat .webchat__send-button__text {
display: none;
}
```
Custom CSS is injected at the page level and targets elements inside the `dealerai-chat`
custom element. Use the `dealerai-chat` selector prefix to scope all rules correctly and
avoid affecting the rest of your website.
Logo and Avatar [#logo-and-avatar]
Dealership Logo [#dealership-logo]
Upload a logo under **Settings → Webchat → Logo**. The logo appears in the chat window header
alongside the widget title. Accepted formats: PNG, JPG, SVG. Recommended size: 120 × 40 px.
Bot Avatar [#bot-avatar]
Upload a custom avatar image under **Settings → Webchat → Avatar**. The avatar is shown next
to every bot message bubble inside the chat window. Recommended size: 48 × 48 px (square).
Bot Framework WebChat Style Overrides [#bot-framework-webchat-style-overrides]
The chat area (after the customer engages) is rendered by Microsoft Bot Framework WebChat.
You can override its internal style variables by injecting CSS that targets Bot Framework's
CSS classes within the `dealerai-chat` scope:
```css
/* Make bot message bubbles use a custom font */
dealerai-chat .webchat__bubble__content {
font-family: 'Your Brand Font', sans-serif;
}
/* Adjust suggested action button appearance */
dealerai-chat .webchat__suggested-actions__button {
border-radius: 20px;
font-size: 13px;
}
```
Bot Framework WebChat CSS class names are prefixed with `webchat__`. You can inspect
the rendered HTML in DevTools to discover the exact class names for any element you
want to style.
Disabling Audio [#disabling-audio]
By default the widget can play audio notifications. To disable audio support, turn off
**Settings → Webchat → Enable Audio Support** in the portal.
# Webchat (/docs/webchat)
The DealerAI Webchat widget is an embeddable chat component that lets customers start a
conversation with your AI directly from your dealership website. It connects to the full
DealerAI platform — the AI can answer questions, book appointments, surface inventory, and
hand off to a human agent when needed.
Overview [#overview]
How it Works [#how-it-works]
1. A visitor opens the chat widget on your dealership website
2. The widget connects to the DealerAI bot engine via a secure DirectLine session
3. The AI responds in real time using your configured agents, inventory, and Knowledge Base
4. If the customer books an appointment or submits a lead, it flows into the DealerAI portal automatically
Architecture [#architecture]
The widget ships as a **Web Component** (``) that bootstraps a full React
application inside an isolated Shadow DOM. This means the widget's styles never conflict with
your website's existing CSS, and no extra style isolation is needed on your end.
Communication between the widget and your website JavaScript happens through the
[`window.DealerAI` SDK](/docs/webchat/sdk) and custom DOM events.
Prerequisites [#prerequisites]
Before going live with the webchat widget:
* Your dealership is set up in the DealerAI portal
* The **Webchat** channel is enabled under **Settings → Activation & Features**
* Widget appearance is configured under **Settings → Webchat**
* You have tested the widget using [Preview](/docs/portal/preview)
# Installation (/docs/webchat/installation)
The DealerAI webchat widget loads as a custom HTML element via a single JavaScript snippet.
Add it once to your website and the widget will appear on every page automatically.
Embed Code [#embed-code]
Add the following snippet to every page of your dealership website, just before the closing
`` tag:
```html
```
Replace `YOUR_DEALER_ID` with your dealership's ID, which you can find in the DealerAI portal
under **Settings → General Info**.
Attributes [#attributes]
You can pass optional attributes to pre-fill customer information or adjust widget behaviour:
| Attribute | Required | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------- |
| `data-dealer-id` | Yes | Your dealership ID — identifies which configuration to load |
| `data-name` | No | Pre-fill the customer's display name in the chat |
| `data-email` | No | Pre-fill the customer's email address |
| `data-phone` | No | Pre-fill the customer's phone number |
| `data-cid` | No | Pass an external customer ID (e.g. CRM contact ID) to associate with the session |
| `data-expand-mode` | No | Opens the widget in an expanded/full-width layout — useful for dedicated chat pages |
| `data-override-private` | No | Present on the element (no value needed) to bypass private-mode restrictions |
| `data-url` | No | Override the base URL the widget loads assets from — defaults to the script origin |
Example with pre-filled customer data [#example-with-pre-filled-customer-data]
If your website has a logged-in customer portal, you can pass known customer details so
they don't have to re-enter them in the chat:
```html
```
Example with expand mode [#example-with-expand-mode]
Use `data-expand-mode` to embed a full-size chat interface inside a dedicated page or container,
rather than as a floating corner widget:
```html
```
Deferred initialisation [#deferred-initialisation]
By default, the widget initialises as soon as the script loads. To take control of when it
starts, add `?initialize=false` to the script `src` and call
[`window.DealerAI.load()`](/docs/webchat/sdk#load) when you are ready:
```html
```
Placement Recommendations [#placement-recommendations]
* Add the snippet to your **global site template** so it appears on every page
* Place it in the `` — avoid placing it in ``
* If you use a **tag manager** (e.g., Google Tag Manager), inject the snippet via a custom
HTML tag fired on All Pages
Verifying the Installation [#verifying-the-installation]
After adding the snippet:
Open your website in a browser
Look for the chat button in the bottom corner of the page
Click the button to open the widget and send a test message
Confirm the AI responds with your dealership's configured greeting
If the widget does not appear, check that:
* The `data-dealer-id` attribute is set correctly
* The Webchat channel is enabled in **Settings → Activation & Features**
* There are no JavaScript errors in the browser console blocking the script
Content Security Policy (CSP) [#content-security-policy-csp]
If your website uses a Content Security Policy, add the following directives to allow the
widget to load and connect to the DealerAI services:
```
script-src 'self' https://webchat.dealerai.com;
connect-src 'self' https://webchat.dealerai.com https://engine.dealerai.com;
frame-src 'self' https://webchat.dealerai.com;
font-src 'self' https://fonts.gstatic.com;
style-src 'self' https://webchat.dealerai.com https://fonts.googleapis.com;
```
The widget runs in an isolated Shadow DOM to prevent CSS conflicts with your website's
existing styles. No additional style isolation is needed on your end.
# JavaScript SDK (/docs/webchat/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 [#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.
```html
```
***
Methods [#methods]
`api(payload)` [#apipayload]
The primary method for sending commands to the widget.
```javascript
window.DealerAI.api({ action: 'ACTION_NAME', data: { /* ... */ } });
```
| Action | Description |
| ----------- | --------------------------------------------------------- |
| `openchat` | Open the chat window |
| `closechat` | Close the chat window |
| `send` | Open the chat and send a message or metadata to the AI |
| `message` | Send a raw message to the chat without opening the window |
| `reset` | Reset the conversation and start a new session |
Open the chat window [#open-the-chat-window]
```javascript
window.DealerAI.api({ action: 'openchat' });
```
Close the chat window [#close-the-chat-window]
```javascript
window.DealerAI.api({ action: 'closechat' });
```
Open the chat and send a message [#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:
```javascript
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:
| Field | Type | Description |
| ------ | -------- | -------------------------------------------------------------- |
| `vin` | `string` | VIN of the vehicle the customer is interested in |
| `hint` | `string` | Contextual hint passed to the AI to guide the opening response |
Reset the conversation [#reset-the-conversation]
```javascript
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()` [#load]
Initialise the widget. Only needed when you have set `?initialize=false` on the script URL
to defer widget startup.
```javascript
window.DealerAI.load();
```
See [Deferred initialisation](/docs/webchat/installation#deferred-initialisation) for the
full usage pattern.
***
`unload()` [#unload]
Completely unmount the widget from the page and remove all event listeners.
```javascript
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)` [#addlistenerevent-callback]
Register a callback for a named widget event.
```javascript
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 [#available-events]
| Event | Payload | Description |
| ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `lead` | `{ leadId, conversationId, ... }` | A lead was captured during the chat |
| `appointment` | `{ appointmentId, conversationId, ... }` | An appointment was booked |
| `price-enquiry-clicked` | Custom | Custom API event dispatched by an [action button](/docs/webchat/action-buttons#action-button-api-events) |
Custom API event names are defined in the action button configuration in the portal.
The event name you listen for must match the `payload.message` value configured for
that button.
***
`removeListener(event)` [#removelistenerevent]
Remove a previously registered event listener.
```javascript
window.DealerAI.removeListener('lead');
```
***
`raiseEvent(event, payload)` [#raiseeventevent-payload]
Manually fire a registered listener. Useful for testing integrations without waiting for
the real event to occur.
```javascript
window.DealerAI.raiseEvent('lead', { conversationId: 'test-123' });
```
***
Full Integration Example [#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
```html
```
Analytics Events [#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**.
| GA4 / ASC event | Trigger |
| ----------------- | ----------------------------- |
| Chat impression | Widget is displayed on page |
| Chat click / open | Customer opens the widget |
| Lead | Customer submits a lead form |
| Appointment | Customer books an appointment |
GA4 events are only fired if the `window.google_tag_manager` object is present on the
page. If you use a tag manager such as Google Tag Manager, ensure the GTM container
fires on all pages before the DealerAI widget script.
# AI Agents (/docs/portal/agents)
The **AI Agents** section is where you manage the dealership-facing agents that power DealerAI conversations and bookings.
Overview [#overview]
In the current portal UI, the Agents screen includes:
* A **Train AI** action in the page header
* An **Add** action for creating or adding agent records
* A left sidebar grouping agent types and related configuration areas
* A **Default Agents** group containing built-in appointment agents
* Additional groups for **Custom Agents** and **Outbound Agents** when enabled
* A main editor area for the selected agent's settings
Default agents [#default-agents]
The built-in default agents currently shown in the portal are:
* **Service Agent**
* **Test Drive Agent**
* **Sales Agent**
* **Lease Return Agent**
* **Parts Agent**
* **Trade-In Agent**
Agent edit view [#agent-edit-view]
When you open an agent such as **Service Agent**, the editor can include configuration areas such as:
* Operating hours by day of week
* Appointment booking enablement
* Agent-specific instructions and behavior
* Availability or scheduling constraints
The exact fields vary by agent type, but the overall workflow stays consistent: pick an agent from the sidebar, edit its settings, then save and retrain if needed.
Custom and outbound agents [#custom-and-outbound-agents]
Beyond the default appointment agents, the sidebar can also expose:
* **Custom Agents** for dealership-specific use cases
* **Outbound Agents** for proactive outreach scenarios
Use these areas when the standard Sales / Service / Test Drive flows are not enough.
Train AI [#train-ai]
Use **Train AI** after meaningful changes to prompts, appointment behavior, or other agent settings.
This refreshes the AI configuration used by DealerAI so the portal settings and real customer-facing behavior stay in sync.
Typical workflow [#typical-workflow]
Open
**Agents**
from the portal navigation.
Select the dealership you want to work in.
Choose a default, custom, or outbound agent from the left sidebar.
Update the relevant fields in the main editor panel.
Save your changes.
Click
**Train AI**
when the change should affect live AI behavior.
Notes [#notes]
* The sidebar contents can change depending on enabled features.
* Some agent sections are dealership-specific, while others depend on organization-level setup.
* If an agent controls booking behavior, review the related **Appointments** and **Reach** settings as part of the same workflow.
# Analytics (/docs/portal/analytics)
The Analytics section provides visual dashboards so you can track how well DealerAI is performing
for your dealership — how many conversations are happening, how leads are converting, and where
customers are dropping off.
Overview [#overview]
Analytics data is drawn from all conversations and interactions across every connected channel.
Charts and metrics refresh periodically and can typically be filtered by date range and
dealership.
Available Dashboards [#available-dashboards]
Conversation Analytics [#conversation-analytics]
The main analytics dashboard focuses on conversation and lead performance:
| Metric | Description |
| ------------------------ | ------------------------------------------------------------ |
| **Total conversations** | Number of unique conversation threads in the selected period |
| **Active conversations** | Conversations currently in progress |
| **Messages sent** | Total outbound messages sent by the AI and staff |
| **Human takeovers** | How often staff manually joined a conversation |
Conversion Metrics [#conversion-metrics]
Tracks how conversations turn into outcomes:
| Metric | Description |
| ----------------------- | --------------------------------------------------------- |
| **Leads generated** | Customers who expressed buying or service intent |
| **Appointments booked** | Appointments created by the AI during conversations |
| **Appointment rate** | Percentage of leads that resulted in a booked appointment |
Channel Breakdown [#channel-breakdown]
A visual breakdown of conversation volume by channel (WebChat, SMS, Facebook, etc.) helps you
understand where customers prefer to engage.
Interpreting the Charts [#interpreting-the-charts]
Appointment rate is one of the most important indicators of AI effectiveness. A low rate may
signal that the AI agent prompts or conversation flows need tuning — review the Agents section
for configuration options.
* **Trends over time** — bar or line charts show daily or weekly activity so you can spot busy
periods and seasonal patterns
* **Top conversation topics** — categories of questions customers are asking most often
* **Response time** — how quickly the AI (and your staff) are responding to inbound messages
Date Range Filtering [#date-range-filtering]
Use the date picker at the top of the dashboard to select a custom reporting window. Presets such
as **Last 7 days**, **Last 30 days**, and **This month** are available for quick access.
Exporting Data [#exporting-data]
Where available, use the export button to download report data as a CSV for further analysis in
Excel or your CRM.
# Appointments (/docs/portal/appointments)
The **Appointments** section is the scheduling workspace for dealership bookings created or managed through DealerAI.
Calendar view [#calendar-view]
The current Appointments page supports two operating modes:
* **Calendar View**
* **Table View**
Calendar View is ideal for schedule review, while Table View is better for list-based operational work.
The sidebar includes filtering controls for:
* **View Mode**
* **Appointment Type**
The visible appointment-type filters currently include:
* Service
* Test Drive
* Sales
* Parts
* Trade-In
* Lease Return
Appointment detail [#appointment-detail]
Clicking a calendar item opens an appointment detail workflow so users can review the booking more closely and continue into related follow-up actions.
The page also includes a sequence panel so staff can continue follow-up after reviewing a booking.
Typical workflow [#typical-workflow]
Open
**Appointments**
from the navigation.
Choose
**Calendar View**
or
**Table View**
.
Filter by the appointment types you want to review.
Open a booking from the calendar or list.
Use related sequence or conversation tools if post-booking follow-up is needed.
Notes [#notes]
* Appointments is dealership-specific.
* The appointment-type filter is especially useful when different teams handle different booking categories.
* This page is closely related to **Agents** and **Reach**, since agent settings and follow-up rules directly affect the appointment workflow.
# Contacts (/docs/portal/contacts)
The **Contacts** section is the portal's customer record workspace for dealership teams.
Contacts list [#contacts-list]
The current Contacts page includes a table with these main columns:
* **Name**
* **Enroll**
* **Phone**
* **Email**
* **In Sequence**
* **Date Created**
* **Last Modified**
At the top of the page, users can access actions such as:
* **Unsubscribed**
* **Enroll**
* **Add**
* **Delete**
Contact detail view [#contact-detail-view]
When you open a contact, the portal provides a detail workflow for reviewing and editing customer information.
Depending on the record, this can include fields such as:
* First name
* Last name
* Phone number
* Email
* Address
* Postal code
* Province
* Country
Unsubscribed users [#unsubscribed-users]
The Contacts section also includes an **Unsubscribed Users** subpage showing phone numbers that have been opted out or marked unsubscribed by downstream messaging behavior.
Use this area when documenting consent-sensitive communication workflows.
Sequence enrollment [#sequence-enrollment]
The Contacts view includes an enrollment flow with fields for:
* **Select Sequence**
* **Start Date**
This makes it easy to move a contact directly into an automated outreach sequence without leaving the Contacts section.
Typical workflow [#typical-workflow]
Open
**Contacts**
from the navigation.
Search or scan the table to find the customer you need.
Open the contact or use the top actions to enroll, add, or remove records.
Update the customer's details as needed.
Use sequence enrollment when the contact should enter a follow-up workflow.
Notes [#notes]
* Contacts are dealership-specific.
* The **Unsubscribed** flow is important when documenting consent-sensitive outreach processes.
* Contacts works closely with **Leads**, **Reach**, and **Sequences** in the overall customer journey.
# Conversations (/docs/portal/conversations)
The Conversations section is where you can watch AI-led chats happening in real time and step in
to assist or take over when needed. Every inbound message — whether from WebChat, SMS, Facebook,
Instagram, or Google Chat — appears here.
Overview [#overview]
When a customer starts a conversation, DealerAI's AI agents handle the interaction automatically.
The Conversations screen lets your team observe those exchanges, send manual messages, and review
conversation history alongside customer details.
Navigating the Conversations List [#navigating-the-conversations-list]
The left panel shows all active and recent conversations for the selected dealership. Each
conversation card displays:
* Customer name or phone number
* Channel icon (SMS, WebChat, Facebook, etc.)
* Last message preview and timestamp
* Status indicator (active, waiting, resolved)
Use the **dealership selector** at the top to switch between stores if your account has access to
multiple locations.
Conversation Detail [#conversation-detail]
Clicking a conversation opens the full chat view:
* **Message thread** — the complete conversation history between the customer and the AI (or a
staff member)
* **Customer info sidebar** — name, phone, email, channel, and any linked contact record
* **Conversation history** — previous interactions with the same customer
Taking Over a Conversation [#taking-over-a-conversation]
When a staff member sends a message, the AI pauses on that conversation so the human agent is
in full control. The AI resumes when the conversation is resolved or after a configured
inactivity period.
To send a manual message:
Click the conversation you want to join
Type your message in the input box at the bottom of the thread
Press
**Send**
— the message is delivered through the same channel the customer is using
Channel Icons [#channel-icons]
| Icon | Channel |
| -------------- | ------------------------- |
| Chat bubble | WebChat (embedded widget) |
| Phone | SMS |
| Facebook logo | Facebook Messenger |
| Instagram logo | Instagram Direct Message |
| Google logo | Google Chat |
| Envelope | Email |
Filtering and Search [#filtering-and-search]
Use the search bar above the conversation list to find conversations by customer name or phone
number. Conversations are also grouped by status so you can quickly focus on those that need
attention.
Real-Time Updates [#real-time-updates]
The conversation list updates in real time. New messages and status changes appear automatically
without refreshing the page.
# Holidays (/docs/portal/holidays)
The Holidays section lets you tell DealerAI about dates when your dealership will be closed or
operating on reduced hours. The AI uses this information to set accurate customer expectations
during conversations — for example, informing a customer enquiring on Christmas Day when the
dealership will next be open.
Overview [#overview]
Without holiday configuration, the AI relies solely on your regular hours from the
[Knowledge Base](/docs/portal/knowledge-base) and [Settings](/docs/portal/settings). Adding
specific closure dates ensures the AI never promises a same-day appointment on a day you're
actually closed.
Holidays List [#holidays-list]
The Holidays page shows a list or calendar of all configured closure dates. Each entry includes:
| Field | Description |
| ------------- | ----------------------------------------------------------------------------------- |
| **Name** | A label for the holiday (e.g., "Christmas Day", "Statutory Holiday") |
| **Date** | The specific date the dealership is closed |
| **Recurring** | Whether the holiday repeats annually on the same date |
| **Note** | Optional message the AI can share with customers (e.g., "We reopen on January 2nd") |
Adding a Holiday [#adding-a-holiday]
Click
**Add Holiday**
on the Holidays page
Enter the
**Name**
of the holiday
Select the
**Date**
from the date picker
Tick
**Recurring**
if this closure happens every year on the same date
Optionally add a
**Note**
— the AI may include this in responses (e.g., the next available date)
Click
**Save**
Editing and Removing Holidays [#editing-and-removing-holidays]
Click any holiday entry to edit or delete it. If a one-time closure has passed, you can safely
delete it to keep the list current — or leave it if it recurs annually.
How the AI Uses Holiday Data [#how-the-ai-uses-holiday-data]
When a customer contacts the dealership during a configured holiday:
* The AI informs them that the dealership is currently closed
* If a note is provided, the AI shares the expected reopening date
* The AI can still take a message or capture the customer's details so staff can follow up when
the dealership reopens
Appointment booking is automatically disabled for holiday dates. The AI will not offer
appointment slots on days marked as closures.
Recommended Holidays to Configure [#recommended-holidays-to-configure]
Set up closures for any date your dealership will be fully or partially closed:
* National statutory holidays (New Year's Day, Canada Day, Christmas, etc.)
* Long weekend closures
* Staff training days
* Inventory days or annual shutdowns
# Inventory (/docs/portal/inventory)
The **Inventory** section is the portal workspace for dealership vehicle inventory.
Inventory overview [#inventory-overview]
The current Inventory page shows separate sections for:
* **New Cars**
* **Used Cars**
The header also displays summary counts for the currently visible new and used inventory.
Inventory detail view [#inventory-detail-view]
When a vehicle is selected, the portal opens a detail workflow so users can inspect an individual unit more closely without losing the broader inventory context.
What users can do [#what-users-can-do]
From the Inventory page, dealership staff can:
* Review visible inventory counts
* Browse vehicle cards in the current result set
* Switch through paginated new and used inventory lists
* Open a vehicle to inspect more details
The list presents each vehicle as a quick summary card, typically including price, store label, model year, make and model, and trim.
Typical workflow [#typical-workflow]
Open
**Inventory**
from the navigation.
Review the visible new and used counts in the header.
Browse the current vehicle cards or page through additional results.
Open a vehicle when you need to inspect its details more closely.
Confirm the inventory shown here matches the dealership's expected live stock.
Notes [#notes]
* Inventory is dealership-specific.
* The page is split between new and used listings rather than a single undifferentiated list.
* Inventory documentation pairs well with **Promotions** and **Knowledge Base** when describing how DealerAI answers vehicle questions.
# Knowledge Base (/docs/portal/knowledge-base)
The **Knowledge Base** section is where dealership-specific reference content is maintained for DealerAI.
Knowledge editor [#knowledge-editor]
The current Knowledge Base experience includes:
* A page header showing the number of knowledge bases and training status
* Top actions for **Save**, **Train AI**, and **Cancel**
* A **Table of Contents** sidebar
* A structured content editor for dealership knowledge entries
This is the central place for editing the facts and reference material DealerAI relies on during conversations.
Extract workflow [#extract-workflow]
The Knowledge Base also includes an **Extract** subpage for pulling site content from a URL.
Use this when you want to seed or refresh dealership facts from an existing website before reviewing and saving the results.
Structured knowledge editing [#structured-knowledge-editing]
Knowledge Base content is maintained in structured entries rather than one large freeform document.
The editor supports workflows such as:
* Updating descriptors or labels
* Editing long-form paragraph content
* Moving between knowledge sections from the sidebar
* Saving or canceling pending changes
Typical workflow [#typical-workflow]
Open
**Knowledge Base**
from the navigation.
Select the dealership you want to manage.
Use the
**Table of Contents**
to jump to the section you want to edit.
Update the structured knowledge entries.
Click
**Save**
, then use
**Train AI**
if the changes should affect production responses.
Notes [#notes]
* Knowledge Base is dealership-specific.
* This section is a major source of truth for customer-facing AI answers.
* Changes here often work best when coordinated with updates in **Agents**, **Reach**, or **Settings**.
# Leads (/docs/portal/leads)
The **Leads** section is the dealership lead-review workspace in the DealerAI portal.
Leads list [#leads-list]
The current Leads page shows:
* A **Start Date** picker
* An **End Date** picker
* A dealership-scoped leads table
* A sequence-enrollment panel beneath the table
The visible lead columns include:
* **Name**
* **Phone**
* **Email**
* **Date/Time**
* **Type**
* **Channel**
Sequence panel [#sequence-panel]
The lower section of the page includes quick sequence controls such as:
* **Select Sequence**
* **Start Date**
This supports immediate handoff into automated outreach when a lead should continue through Reach or Sequences.
Working a lead [#working-a-lead]
From the Leads section, dealership staff can:
* Narrow the list by a date range
* Review the recent leads in the selected window
* Inspect how the lead entered the system
* Use the sequence panel to place the lead into a follow-up workflow
Typical workflow [#typical-workflow]
Open
**Leads**
from the navigation.
Set the
**Start Date**
and
**End Date**
for the period you want to review.
Inspect the table for lead type, channel, and timing.
Open the related conversation or customer record when more context is needed.
Use sequence enrollment when the lead should move into follow-up.
Notes [#notes]
* Leads is dealership-specific.
* This page is optimized for reviewing and triaging recent lead activity.
* Pair this page with **Reach** and **Contacts** documentation when describing a complete lead-management workflow.
# Mailbox (/docs/portal/mailbox)
The Mailbox is a centralised email inbox for your dealership's inbound lead communications. It
captures emails and ADF (Auto/Lead Data Format) leads arriving from listing sites like
AutoTrader.com, Cars.com, and your own website, presenting them in a familiar email-style
interface.
What is an ADF Lead? [#what-is-an-adf-lead]
ADF (Auto/Lead Data Format) is the automotive industry-standard XML format used by vehicle
listing platforms and dealership websites to transmit customer enquiry data. When a customer
submits an enquiry form on AutoTrader or your dealership website, the platform sends an ADF
message to your DealerAI inbox.
DealerAI automatically parses the ADF data — extracting the customer's name, contact
information, and vehicle interest — and initiates a personalised response via SMS or email on
your behalf.
Navigating the Mailbox [#navigating-the-mailbox]
The Mailbox uses a three-panel layout:
| Panel | Content |
| ---------------- | ------------------------------------------- |
| **Left sidebar** | Folder navigation (Inbox, Sent, etc.) |
| **Centre panel** | List of messages in the selected folder |
| **Right panel** | Full message content for the selected email |
Folders [#folders]
| Folder | Contains |
| --------- | ------------------------------------------------- |
| **Inbox** | All inbound emails and ADF leads |
| **Sent** | Outbound messages sent by DealerAI on your behalf |
Use the folder sidebar to switch between views. The inbox count shows the number of unread or
unprocessed messages.
Reading a Message [#reading-a-message]
Click any message in the centre list to open it in the right panel. For ADF leads, the panel
displays the parsed customer details:
* Customer name, phone, and email
* Vehicle(s) of interest
* Enquiry type (purchase, trade-in, financing, etc.)
* Original enquiry text
* Source (the listing site or form that submitted the lead)
Automatic Lead Processing [#automatic-lead-processing]
DealerAI handles ADF leads automatically. When a new ADF email arrives, the system parses the
lead, creates a contact record, and sends an AI-generated response to the customer via their
preferred channel — without any manual action required.
You can review the automated response that was sent by clicking the linked conversation from the
message detail panel.
Manual Follow-Up [#manual-follow-up]
If an ADF lead requires personal attention or the automated response was insufficient, open the
linked conversation from the message detail and send a manual message directly to the customer
via the Chat Panel.
# Organizations (/docs/portal/organizations)
The Organizations section provides administrative control over the multi-location structure of
your DealerAI account. It is used by organization administrators to manage stores (individual
dealership locations) and the staff members who have access to each one.
The Organizations section is only visible to users with the **Admin** or **Org Admin** role.
Standard dealership users do not see this section.
Overview [#overview]
DealerAI supports multi-tenant organizations — a single organization can manage multiple
dealership stores. The Organizations section is the control centre for that structure.
| Area | Purpose |
| ---------- | ------------------------------------------------------------------------ |
| **Stores** | View and configure all dealership locations in the organization |
| **Staff** | Manage the people who have access to the portal and their assigned roles |
Stores [#stores]
The Stores page lists every dealership location belonging to your organization.
Stores List [#stores-list]
Each row in the stores table shows:
| Column | Description |
| -------------- | ------------------------------------------- |
| **Store name** | The display name of the dealership location |
| **Location** | City or address |
| **Status** | Active or inactive |
| **Users** | Number of staff assigned to this store |
Store Detail [#store-detail]
Click any store to open its detail view, which includes several tabs:
| Tab | Contents |
| ----------------- | ------------------------------------------------------------- |
| **Details** | Name, address, timezone, and other store metadata |
| **Users** | Staff members who have access to this store, with their roles |
| **Manufacturers** | Vehicle brands sold by this store |
| **Configuration** | Advanced NLP and platform-specific settings |
Adding a New Store [#adding-a-new-store]
Go to
**Organizations → Stores**
and click
**Add Store**
Enter the store name, address, and timezone
Select the manufacturers the store sells
Click
**Save**
— the new store is created and can now be configured fully
Assigning Users to a Store [#assigning-users-to-a-store]
Open the store in the stores list
Navigate to the
**Users**
tab
Click
**Add User**
and search for the staff member by name or email
Select their
**Role**
(Admin, Org Admin, or User) for this store
Click
**Save**
Staff [#staff]
The Staff page manages the professional profiles of everyone who has access to your organization's
portal.
Staff List [#staff-list]
The staff list shows all personnel in the organization:
| Column | Description |
| ---------- | ----------------------------------------------- |
| **Name** | Staff member's full name |
| **Email** | Login email address |
| **Role** | Organization-level role |
| **Stores** | Number of stores the staff member has access to |
Use the search bar to filter staff by name or email.
Staff Profile [#staff-profile]
Click any staff member to view their profile:
* Full name, email, and profile photo (via Gravatar)
* Assigned stores and roles
* Account status
Adding a Staff Member [#adding-a-staff-member]
Click
**Add Staff**
from the staff list
Enter the staff member's name and email address
Assign an organization-level role
Click
**Save**
— the staff member receives an email invitation to set their password
Editing and Removing Staff [#editing-and-removing-staff]
Open a staff profile and click **Edit** to update their details. To remove a staff member from
the organization, open their profile and use the **Remove** option. This revokes all portal
access immediately.
Removing a staff member from the organization removes their access to all stores and cannot be
undone without re-inviting them.
# Preview (/docs/portal/preview)
The Preview section gives you a sandboxed environment to interact with your DealerAI webchat
widget exactly as your website visitors will experience it — before making any changes live on
your site.
Overview [#overview]
Preview renders a simulation of your dealership's website with the chat widget overlaid on top.
You can open the widget, send test messages, and see how the AI responds using your current
configuration, agent prompts, inventory, and Knowledge Base.
Conversations started in Preview are test conversations. They do not create real leads, book
actual appointments, or trigger Reach sequences.
Using Preview [#using-preview]
Navigate to
**Preview**
in the sidebar and select your dealership
The preview frame loads showing a simulated dealership page with the chat widget in the corner
Click the widget button to open the chat window
Type a message as if you were a customer — for example, "Do you have any trucks under $50,000?"
Observe how the AI responds using your current inventory, prompts, and settings
What to Test [#what-to-test]
Use Preview to verify the experience before going live or after making configuration changes:
| What to check | How |
| ----------------------- | ------------------------------------------------------------------- |
| **Greeting message** | Open the widget and check the first message displayed |
| **Widget appearance** | Confirm the colours, logo, and title match your branding |
| **Inventory accuracy** | Ask about specific vehicles and check the AI uses up-to-date stock |
| **Knowledge Base** | Ask about hours, location, or policies and verify the answers |
| **Promotions** | Ask about current deals and confirm active promotions are mentioned |
| **Appointment booking** | Go through a full booking flow to test the end-to-end experience |
After Testing [#after-testing]
If you find issues in Preview:
* **Incorrect AI responses** — update the relevant agent prompt in [Agents](/docs/portal/agents)
* **Wrong dealership info** — update [Knowledge Base](/docs/portal/knowledge-base) or [Settings](/docs/portal/settings)
* **Missing or wrong vehicles** — review the [Inventory](/docs/portal/inventory) list
* **Widget appearance issues** — adjust the Webchat settings in [Settings → Webchat](/docs/portal/settings)
Re-open Preview after each change to confirm the issue is resolved before going live.
# Promotions (/docs/portal/promotions)
The **Promotions** section is where dealership-specific offers and specials are managed in the portal.
Promotions list [#promotions-list]
The current Promotions page includes:
* A header showing the total number of promotions and training status
* Top actions for **Train AI**, **Add**, and **Delete**
* Table tools for **Filters** and **Columns**
* A dealership-scoped promotions table
The visible table columns include:
* **Promotion Name**
* **Active**
* **Tags**
* **Start Date**
* **End Date**
Extract promotions [#extract-promotions]
The Promotions area also includes an **Extract Promotions** workflow where users can supply a URL and pull promotional content into the portal for review.
This is useful when a dealership already publishes offers elsewhere and wants to bring them into DealerAI more efficiently.
Main actions [#main-actions]
Train AI [#train-ai]
Use **Train AI** after changing promotional content so DealerAI reflects the latest offers in live conversations.
Add [#add]
Create a new promotion record.
Delete [#delete]
Remove one or more selected promotions when they are no longer valid.
Typical workflow [#typical-workflow]
Open
**Promotions**
from the navigation.
Review the current promotions list and filter it if needed.
Add a new offer, edit an existing one, or use the extract flow.
Confirm the active window, tags, and content are correct.
Save the changes and click
**Train AI**
if the update should affect production responses.
Notes [#notes]
* Promotions is dealership-specific.
* Training matters here because promotional content often needs to show up in customer-facing answers quickly.
* Pair this page with **Inventory** and **Knowledge Base** docs when documenting merchandising or campaign workflows.
# Reach (/docs/portal/reach)
**Reach** is DealerAI's automation control center for follow-up and lead-routing behavior across email, SMS, and supported voice flows.
General Configuration [#general-configuration]
The current Reach sidebar includes these pages:
* **General Configuration**
* **Follow Up**
* **Forward Leads**
* **Fall Through**
* **Inbound Sequences**
The **General Configuration** page contains the high-level automation controls, including options for:
* Prioritizing **email** for incoming ADF leads
* Prioritizing **voice** when multiple channels are available
* Enabling **Email Reach Automation**
* Managing inbound and outbound email addresses
* Enabling **SMS** automation
* Enabling **voice** automation when voice settings are configured
* Selecting the voice agent used for Reach flows
Start here when you need to confirm how Reach behaves overall before tuning specific follow-up pages.
Follow Up [#follow-up]
Use **Follow Up** to schedule continued outreach after the initial interaction.
From the current portal UI, this page includes channel-specific controls for:
* **SMS** follow-up
* **Email** follow-up
* **Voice** follow-up
* **Facebook/Meta** follow-up when configured
This is where dealership teams tune ongoing contact timing and channel usage after a customer enters the workflow.
Forward Leads, Fall Through, and Inbound Sequences [#forward-leads-fall-through-and-inbound-sequences]
* Use **Forward Leads** to route incoming ADF leads to the right destinations and providers.
* Use **Fall Through** to define what happens when a lead does not move through the normal path.
* Use **Inbound Sequences** to configure provider- and channel-based automation for inbound ADF leads.
Typical workflow [#typical-workflow]
Open
**Reach**
from the main navigation.
Select the dealership you want to configure.
Review
**General Configuration**
first to confirm the active channels and priorities.
Adjust
**Follow Up**
,
**Forward Leads**
,
**Fall Through**
, or
**Inbound Sequences**
as needed.
Save the updated Reach settings and validate the resulting customer flow.
Notes [#notes]
* Reach is dealership-specific and strongly tied to live automation behavior.
* Channel-specific controls only appear when the dealership is configured for those channels.
* If you are documenting follow-up workflows, pair Reach with **Leads**, **Contacts**, and **Appointments** so the full process is clear.
# Settings (/docs/portal/settings)
The **Settings** section is the main dealership configuration workspace in the DealerAI portal.
General Info [#general-info]
The current Settings sidebar includes these main pages:
* **General Info**
* **Departments**
* **Notifications**
* **Webchat**
* **Analytics Tracking**
* **Facebook & Instagram**
* **SMS**
* **Hours**
* **Activation and Features**
* **Active Messages**
* **Lead Generation**
* **Voice Settings**
* **Whitelisted Domain**
The default landing page is **General Info**, where dealership teams manage core business identity details such as dealership name, website links, reviews URL, locations, and address behavior.
Webchat settings [#webchat-settings]
Use the **Webchat** subsection to configure the customer-facing widget experience.
This is the best place to document the visible chat experience, branding, and embedded widget behavior.
Voice settings [#voice-settings]
Use **Voice Settings** to configure the call experience and phone-agent behavior.
This includes the settings most relevant to voice-agent tone, handling, and telephony-related experience design.
Typical workflow [#typical-workflow]
Open
**Settings**
from the navigation.
Select the dealership you want to configure.
Choose the relevant page from the left sidebar.
Update the fields, toggles, or lists for that area.
Save the changes before moving to another section.
Notes [#notes]
* Settings is one of the most important sections for portal onboarding and day-two administration.
* Role permissions can hide or reveal certain subpages.
* When documenting customer-facing behavior, Settings should usually be read alongside **Reach**, **Webchat**, and **Voice Settings** guidance.
# Subscription (/docs/portal/subscription)
The Subscription section is where you manage your DealerAI plan, review your billing status,
and make changes to your payment details or tier.
Overview [#overview]
DealerAI offers tiered subscription plans based on the number of dealerships, conversation
volume, and features required. Your current plan determines which features are available in
the portal.
Viewing Your Current Plan [#viewing-your-current-plan]
The Subscription page shows:
| Item | Description |
| ------------------- | ------------------------------------------------------ |
| **Current plan** | The active subscription tier and its included features |
| **Billing cycle** | Monthly or annual billing, and the next billing date |
| **Payment method** | The card or payment method on file |
| **Invoice history** | Past invoices available to download as PDF |
Changing Your Plan [#changing-your-plan]
To upgrade or downgrade your subscription:
Navigate to
**Subscription**
in the sidebar
Review the available plans in the pricing table
Click
**Select Plan**
on the tier that suits your needs
Confirm the change — upgrades take effect immediately, downgrades at the end of the current billing period
Plan changes and billing are processed securely through Stripe. DealerAI does not store your
full card details.
Updating Payment Details [#updating-payment-details]
To update your billing card or payment method:
Click
**Update Payment Method**
on the Subscription page
Enter the new card details in the secure Stripe form
Click
**Save**
— your next invoice will be charged to the new method
Cancelling Your Subscription [#cancelling-your-subscription]
To cancel, contact your DealerAI account manager or support team. Upon cancellation:
* Access continues until the end of the current billing period
* Conversation data and configurations are retained for 30 days after cancellation for export
* AI agents stop responding to customers at the end of the active period
Plan Features by Tier [#plan-features-by-tier]
Contact your DealerAI account manager for detailed feature comparisons across plans, or visit
the pricing page from the Subscription section for the latest information.
# Services (/docs/portal/vehicle-services)
The **Services** section manages the dealership service catalog used by DealerAI.
Services list [#services-list]
The current Services page shows:
* A service count in the header
* A **Train AI** action
* An **Add** action
* A list of existing services
This is the main place for maintaining service offerings that should be available to the AI.
Service edit view [#service-edit-view]
When creating or editing a service, the current form includes fields such as:
* **Name**
* **Tags**
* **Description**
* **Cost**
* A **Bookable** option
* **Cancel** and **Save** actions
Train AI [#train-ai]
Use **Train AI** after updating service content so the latest service details are reflected in live AI responses.
This matters whenever the dealership adds, renames, reprices, or changes how a service should be presented.
Typical workflow [#typical-workflow]
Open
**Services**
from the navigation.
Review the current service list.
Click
**Add**
to create a new service or open an existing one to edit it.
Update the service details and save the record.
Use
**Train AI**
when the changes should affect live customer conversations.
Notes [#notes]
* The portal route for this section is `/services`.
* The docs navigation slug remains `vehicle-services`, but the UI label shown in the portal is **Services**.
* Services documentation pairs well with **Knowledge Base** and **Appointments** when documenting service-department workflows.
# Get Conversations with Filtering and Pagination (/docs/api/api/v1/conversation/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Dealership (/docs/api/api/v1/dealership/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Manufacturers (/docs/api/api/v1/manufacturer/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Search Cars (/docs/api/api/v1/search/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Engage Contact (/docs/api/api/v1/ailm/engage/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Add or Update Contact (/docs/api/api/v1/ailm/contact/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/predefined-tasks (/docs/api/api/v1/assistant/predefined-tasks/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads (/docs/api/api/v1/assistant/threads/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant-data/appointments (/docs/api/api/v1/assistant-data/appointments/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant-data/conversations (/docs/api/api/v1/assistant-data/conversations/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant-data/leads (/docs/api/api/v1/assistant-data/leads/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Verify Authentication (/docs/api/api/v1/authentication/verify/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get chats for the authenticated dealer. (/docs/api/api/v1/chats/chats/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Conversation by ConversationId (/docs/api/api/v1/conversation/conversationid/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete All New Cars (/docs/api/api/v1/inventory/new/delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get New Cars (/docs/api/api/v1/inventory/new/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Upload New Inventory CSV (/docs/api/api/v1/inventory/new/put)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete All Used Cars (/docs/api/api/v1/inventory/used/delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Used Cars (/docs/api/api/v1/inventory/used/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Upload Used Inventory CSV (/docs/api/api/v1/inventory/used/put)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Translate Search Query (/docs/api/api/v1/search/translate/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Process ADF Lead (/docs/api/api/v1/ailm/outbound/adf/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/capabilities (/docs/api/api/v1/assistant/threads/capabilities/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/message (/docs/api/api/v1/assistant/threads/message/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId} (/docs/api/api/v1/assistant/threads/threadid/delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId} (/docs/api/api/v1/assistant/threads/threadid/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a single chat conversation by id. (/docs/api/api/v1/chats/chats/conversationid/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Upload New Inventory JSON (/docs/api/api/v1/inventory/new/json/put)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete New Car by VIN (/docs/api/api/v1/inventory/new/vin/delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get New Car by VIN (/docs/api/api/v1/inventory/new/vin/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Upload Used Inventory JSON (/docs/api/api/v1/inventory/used/json/put)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete Used Car by VIN (/docs/api/api/v1/inventory/used/vin/delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Used Car by VIN (/docs/api/api/v1/inventory/used/vin/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get Models by Manufacturer (/docs/api/api/v1/manufacturer/manufacturerid/models/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Notifies DealerAI that a retailer has enabled the CreditApp integration. (/docs/api/api/v1/webhooks/creditapp/integration-enabled/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/predefined-tasks/{taskKey}/execute (/docs/api/api/v1/assistant/predefined-tasks/taskkey/execute/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId}/cancel (/docs/api/api/v1/assistant/threads/threadid/cancel/post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId}/messages (/docs/api/api/v1/assistant/threads/threadid/messages/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId}/runs/{runId} (/docs/api/api/v1/assistant/threads/threadid/runs/runid/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# /api/v1/assistant/threads/{threadId}/runs/{runId}/events (/docs/api/api/v1/assistant/threads/threadid/runs/runid/events/get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}