AI Companion embed — BoaterOS docs

1. The embed

Drop this in your site's <head> or before </body>. That's it. 14KB gzipped, async, no render-blocking.

index.html

<script
  src="https://widget.boater.os/v1/companion.js"
  data-dealer="dlr_4421"
  async></script>

The data-dealer value is your public dealer ID — safe to commit. Find it in Settings → AI Companion → Embed.

2. What you get out of the box

Inventory-aware chat. Answers questions about your hulls, filtered by location and availability.
Inventory-aware voice. Click-to-call picks up on mobile; desktop opens an in-browser voice session.
Appointment booking. Shows your showroom staff's real calendar availability.
Handoff to human. When a user asks for a salesperson by name or triggers a routing rule.
After-hours mode. Captures a lead with consent; a human replies the next morning.

3. Configuration

Most configuration happens in the BoaterOS admin — brand color, voice profile, bounded knowledge sources, after-hours messaging. For things that vary per-page (like scoping to one hull), pass config inline:

config.html

<script>
  window.BOATEROS_CONFIG = {
    context: { hull_id: "hull_YDV48219" },   // scope chat to one boat
    voice_profile: "clay_pnw",              // brand voice preset
    accent_color: "#0C4F3F",                 // override the admin brand color
    launcher_position: "bottom-right",
    auto_open: { after_ms: 45000, once_per_session: true },
  };
</script>
<script src="https://widget.boater.os/v1/companion.js" data-dealer="dlr_4421" async></script>

4. TCPA consent gate

If a visitor gives a phone number for SMS or voice follow-up, the widget inserts a consent line above the submit button — required for TCPA compliance. The line is your choice, with reasonable defaults. The consent event is logged with IP, user agent, exact text shown, and timestamp. See the TCPA consent capture guide for the storage schema.

5. Custom CSS variables

The widget exposes a small set of custom properties. Set them on :root or on #boateros-companion.

widget.css

#boateros-companion {
  --bo-accent: #0C4F3F;
  --bo-bg: #FFFFFF;
  --bo-ink: #061826;
  --bo-radius: 14px;
  --bo-launcher-size: 56px;
  --bo-launcher-offset-x: 24px;
  --bo-launcher-offset-y: 96px; /* clear your own CTA bar */
  --bo-shadow: 0 20px 60px -10px rgba(6, 24, 38, .25);
  --bo-font: "Inter", system-ui, sans-serif;
}

6. Event hooks

The widget dispatches DOM events on window. All of them include a session_id you can correlate with the admin session log.

Event	When it fires
boateros:open	The widget was opened (by click, auto-open rule, or programmatic `.open()`).
boateros:message	Any message sent or received. Includes role, text, and hull context.
boateros:on_lead	Fires when the user shares contact info. Payload: `{ contact_id, channel, consent }`.
boateros:on_qualified	The user met qualification rules (intent + budget + timing). Good event to push to ad pixels.
boateros:on_handoff	The conversation was routed to a human. Payload includes `staff_id` and `reason`.
boateros:close	Widget closed. Includes session duration and message count.

analytics.js

// Push lead events into GA4 + Meta in one place
window.addEventListener("boateros:on_lead", (e) => {
  const { contact_id, channel, consent } = e.detail;

  gtag("event", "generate_lead", {
    lead_source: "ai_companion",
    channel, contact_id,
  });
  fbq("track", "Lead", { content_name: "companion" });
});

7. Analytics and conversion tracking

The widget already reports to the BoaterOS attribution engine — you don't have to wire anything up to see it in the dashboard. Hooks are for when you want to push the same events into your own stack (GA4, Meta, Klaviyo, HubSpot). Do not send raw phone or email to third parties; send contact_id and enrich server-side if you need to.

AI Companion: embedding on your site.