Skip to main content

Embedding overview

The demo is one way to run the assistant. The other is a tag in somebody else's claims system:

<script type="module" src="https://assistant.example.com/claimpilot-assistant.js"></script>

<claimpilot-assistant id="assistant" locale="en-GB" api="https://assistant.example.com"></claimpilot-assistant>

<script>
  document.getElementById('assistant').claim = toClaimpilotClaim(theClaimOnScreen);
</script>

The host hands over the claim it is already displaying. Nothing is fetched, so there is no store to point at, no id to agree on, no second copy to keep in step, and no access decision to make twice: the host decided who could see the claim when it put it on the screen.

We integrate at the claim, not at the tools​

The assistant has sixteen tools. All but the screen action are calculations over one document, not calls to a system. That leaves two ways to plug into a host:

What the host buildsWhat it costs
Integrate at the toolssixteen endpoints matching our contractssixteen integration points per system, and every host reimplements our fraud checks and SLA maths slightly differently
Integrate at the claimone mapping: give us the claimone mapping per system; every tool, capability, prompt and the safety layer stay ours and identical everywhere

We integrate at the claim. The Claim contract is the product's integration contract.

What makes the demo embeddable without a fork​

  • The contract is mostly optional. Eight fields are required; every other section has an empty default. A host maps what it has, and a capability with nothing to work from says so rather than inventing anything.
  • The element renders into a shadow root (frontend/src/embed/element.tsx). Isolation works both ways: our resets do not rearrange the host's page, and an unlayered host rule such as header { background: #fff } cannot beat our utilities. Tailwind's @property registrations are hoisted to the host document, because a shadow root ignores them and borders would quietly disappear.
  • Script order does not matter. A claim assigned before the element is defined lands as an own property that would shadow the accessor. The element takes it back on connect (the property-upgrade pattern), so hosts can load the script wherever suits them.
  • Pointing at the screen is opt-in. With the screen-actions attribute and data-panel regions, the assistant can highlight parts of the host's page. Without it, highlight_panel is never offered to the model, so it cannot claim to have highlighted anything. Anchors are looked up in the host document, so highlighting works from inside the shadow root.
  • Feedback goes to the host as well as to us. Each vote fires claimpilot-feedback (bubbling, composed) with the vote, question and answer, so the host can file it against its own claim and user. We store the vote without the question and answer unless the element has feedback-content.
  • Docking means something different. In the app, the shell gives the docked panel a column and reflows. Embedded, there is no shell and the element's own box is 0×0, so the panel pins itself to the viewport and covers the right of the page (DockPlacement overlay).
  • Its own memory. The element keeps its open-or-docked state under its own localStorage key, so a handler who docked the demo on the same origin does not find a host page opening into a panel.

What a host does not get​

  • The Prompt Lab. There is no browser-held override to send, so prompts are whatever the deployment ships, and a change of tone is a release on our side.
  • The claims list, claim screens, demo hints and generator. The host's product is the claim screen.

The pieces​

WhereWhat
frontend/src/embed/element.tsxThe custom element: properties, attributes, shadow root, the feedback event
frontend/src/embed/EmbeddedAssistant.tsxThe same ChatWidget, composed for a host: pinned region, overlay dock, embed feedback options
frontend/src/embed/embed.cssThe shadow-root stylesheet
frontend/vite.embed.config.tsThe second build: one script, dist/claimpilot-assistant.js. npm run build runs both builds
frontend/public/claimpanion.htmlClaimpanion: a pretend claims system with its own markup, no framework and no build step, that prints its own integration on the page