Amargi Widget
Last updated: 2026-05-29
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)
- Open widget.amargicreative.com and click "New publication". Pick the source (an Agents agent, a Reach Webchat channel, or an Escalate form / KB).
- Pick a UI theme (Classic — speech bubble, Modern — rounded panel, Minimal — slim pill). Live preview is inline in the editor.
- 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
- Open the editor, General tab.
- Switch the "UI theme" radio — the editor auto-saves.
- The Snippet tab will show the updated SDK path (v1 / v2 / v3). Copy it to your site once.
Restrict a publication to specific domains
- Origins tab, add each origin on its own line.
- Use *.example.com to match every subdomain.
- Changes take effect immediately — no re-publish needed.
Pause a publication
- General tab, change the status to "Paused".
- A paused publication 404s on the resolver. The widget fails silently on your site (no bubble) — the visitor sees no error.
- 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.