@mapled/support

@mapled/support

The support window of Mapled: a chat button in the corner of any site. A visitor writes to the project's team; the conversation lands in the project's Inbox in Mapled, the team's answers come back in the window and by email, and the visitor's email replies land in the same conversation.

Turn the project's Inbox on in Mapled first. While it's off, the widget doesn't show.

A script tag

<script src="https://cdn.jsdelivr.net/npm/@mapled/support@0.1.0/dist/support.js" data-mapled-key="mk_live_…" defer></script>

The address names a version: a new release never changes a page that didn't ask for it. The key is the project's delivery key (Mapled: Integrations → Your site; it starts with mk_live_), the one the site already reads content with. It is public by design. Never put a server key (msk_live_), an agent token (mcp_live_) or a webhook secret (whsec_) into a page.

Attribute	What it does
data-mapled-key	the delivery key (required)
data-mapled-position	left puts the button in the bottom-left corner (right by default)
data-mapled-accent	the button's and the visitor's messages' color, a hex value like #2f6bff
data-mapled-title	the panel's title (the project's name by default)
data-mapled-api	another API origin

To open the window from the site's own "Contact" link:

<a href="#" onclick="window.MapledSupport.open(); return false">Contact us</a>

React

import { SupportWidget } from "@mapled/support/react";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <SupportWidget deliveryKey={import.meta.env.VITE_MAPLED_KEY} accent="#2f6bff" />
    </>
  );
}

The component renders nothing in place: the widget mounts itself in the page's corner and goes away with the component. key is React's own prop, so the delivery key goes by deliveryKey.

Without a framework

import { mountSupportWidget } from "@mapled/support";

const widget = mountSupportWidget({ key: "mk_live_…", position: "right" });
widget.open();

mountSupportWidget returns open(), close(), destroy() and ready — a promise of true once the button shows, false when the project doesn't take messages. createSupportClient gives the same calls without the window, for a form of your own; its failures are SupportErrors with the API's status, code and message. Both talk to DEFAULT_API (https://api.mapled.io) unless apiUrl says otherwise.

What it keeps and sends

• The widget sends the visitor's email, optional name, message and the page they wrote from (its address without the query or fragment) to /v1/delivery/inbox/conversations.
• Mapled answers with a token for the conversation. It stays in this browser's localStorage, under the delivery key, and goes in a header (X-Mapled-Conversation), never in an address. Mapled keeps only its hash.
• Everything people wrote shows as text, never as markup. The widget lives in a shadow root: the site's styles don't reach it, and its own don't leak out.
• The window is light and carries a small "Powered by Mapled" link under it, and says where the answers also go (the visitor's email).
• An open window checks for answers every 10 seconds while the tab is visible; a closed one doesn't check.
• A visitor may start five conversations an hour and write 30 messages an hour in one. A project takes 300 new conversations a day.