Amargi Widget

Overview

Amargi Widget is the single-snippet embed surface for the Amargi suite. Each "Publication" pairs a source (an Agents agent, a Reach Webchat channel, or an Escalate form / KB) with a UI theme (Classic / Modern / Minimal) and a public key (wid_…). Paste the <script> tag on your site and a ready-made chat bubble appears.

The bundle is fully served from the Amargi domain — about 40 KB per theme (gzip), loaded from the Amargi CDN, CORS-open. The JWT is minted per-visitor at runtime, so no secrets live in the HTML.

Quickstart (3 steps)

1. Open widget.amargicreative.com and click "New publication". Pick the source (an Agents agent, a Reach Webchat channel, or an Escalate form / KB).
2. Pick a UI theme (Classic — speech bubble, Modern — rounded panel, Minimal — slim pill). Live preview is inline in the editor.
3. Copy the <script> snippet from the "Snippet" tab and paste it before </body> on your site. The bubble appears in under five minutes.

The snippet

<script
  src="https://agents-api.amargicreative.com/sdk/v2/amargi-widget.umd.js"
  data-key="wid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  defer
></script>

Swap v2 for v1 or v3 to change the theme (Classic / Minimal). The data-key attribute is unique per publication — copy it from the "Snippet" tab in the editor.

Key concepts

Publication

The core configuration unit. Pairs one source + one theme + one public key + an allowed-origin list + an active/paused flag. Change the theme, the origin list, or the active status without touching code on your site. Each publication has an editor page with tabs: General, Snippet, Origins, Analytics.

Source

• Agents — enables AI mode. The widget talks to an Agents agent with all the usual AI-safety rails (RAG, tool-calls, human handoff).
• Reach — enables live chat. Connects to a Reach Webchat channel; visitor chats with a human agent in the Reach inbox.
• Escalate — enables form + KB-search modes. Form creates an Escalate ticket on submit; KB-search surfaces articles before the visitor types.

UI Theme

• Classic (v1) — a classic speech-bubble glyph, friendly, moderately rounded corners.
• Modern (v2) — rounded panel, very soft corners, brand-forward. Default for new publications.
• Minimal (v3) — slim pill with a "Chat with us" label next to the icon. Premium, looks un-Amargi-branded.

Allowed origins

A list of HTTPS origins allowed to load the publication. Empty list = any origin (default). A non-empty entry enforces a strict whitelist — supports full origins (https://example.com), wildcard patterns (*.example.com), or bare host names (example.com). Off-list origins get a silent 204 instead of the config payload.

Funnel analytics

Every publication tracks three lifetime counters: loads_total, opens_total, messages_total. The first bumps on every widget-config fetch (a page-load with the <script> tag). The second bumps on bubble-click. The third bumps on first message send. Conversion rates between each stage surface in the editor's "Analytics" tab.

Common tasks

Change the theme after publishing

1. Open the editor, General tab.
2. Switch the "UI theme" radio — the editor auto-saves.
3. The Snippet tab will show the updated SDK path (v1 / v2 / v3). Copy it to your site once.

Restrict a publication to specific domains

1. Origins tab, add each origin on its own line.
2. Use *.example.com to match every subdomain.
3. Changes take effect immediately — no re-publish needed.

Pause a publication

1. General tab, change the status to "Paused".
2. A paused publication 404s on the resolver. The widget fails silently on your site (no bubble) — the visitor sees no error.
3. Resume with "Active" anytime.

Delete a publication

Delete is soft — it sets the deleted_at column in the database, so the resolver stops serving the config but the row is retained for audit. To restore, contact support.

Embed reference

Available SDK paths:

• https://agents-api.amargicreative.com/sdk/v1/amargi-widget.umd.js — Classic theme.
• https://agents-api.amargicreative.com/sdk/v2/amargi-widget.umd.js — Modern theme (default).
• https://agents-api.amargicreative.com/sdk/v3/amargi-widget.umd.js — Minimal theme.

Supported <script> attributes:

• data-key — Required. The public publication key (wid_…).
• data-client-id, data-branch-id, data-user-id — optional. Passed to JWT init for sub-tenant scoping (RAG, billing, history).
• defer — recommended. Loads the bundle after HTML parsing.

Integration with other products

• Agents — AI mode invokes an Agents agent with all the usual AI-safety rails. If the agent emits a human_handoff action, the widget transitions to Live mode (if enabled) and hands the transcript across.
• Reach — Live mode connects to a Reach Webchat channel. The conversation lands in the Reach inbox like any other thread — assignments, internal notes, replies.
• Escalate — Form mode creates an Escalate ticket on submit. KB-search mode surfaces published articles. A create_ticket action from an Agents agent transitions the widget to Form mode (if enabled) with the transcript pre-filled in the first textarea.

Getting help

• Email support: contact@amargicreative.com
• Marketing page: /products/widget.