# Embed the AgentPMT Chat Widget > Developer guide for embedding the AgentPMT AI chat widget on your site. Supports product, workflow, and bundle scopes with customizable theming and automatic credential provisioning. Content type: documentation Source URL: https://www.agentpmt.com/docs/embedded-widgets/embed-the-agentpmt-chat-widget Markdown URL: https://www.agentpmt.com/docs/embedded-widgets/embed-the-agentpmt-chat-widget?format=agent-md Category: Embedded Widgets --- # Embed the AgentPMT Chat Widget Give your users a conversational AI agent that can call tools, execute workflows, and make purchases -- all embedded directly in your site as an iframe or floating widget. > INFO: Production URL > > `https://www.agentpmt.com/embed.js` --- ## How It Works The chat embed creates a scoped AI conversation tied to a specific **product**, **workflow**, or **bundle**. When a user opens the chat: 1. They register or sign in with email and password 2. The widget checks whether the scoped tools are on the user's budget 3. If tools are missing, the widget walks the user through adding them and configuring credentials 4. Once everything is provisioned, the AI agent can chat, call tools, and run workflows on the user's behalf All tool and agent usage is billed to the end user's AgentPMT account. The embedding site does not pay for user activity -- costs pass through directly to each user based on their own usage. --- ## Embed Types The chat widget supports three scope types. All three accept the same parameters and follow the same authentication flow. The difference is what tools the AI has access to. - [Product](#product-embed) - Single-tool chat. URL: /embed/product/{id-or-slug} - [Workflow](#workflow-embed) - Multi-step workflow chat. URL: /embed/{id-or-slug} - [Bundle](#bundle-embed) - Multiple tools and workflows. URL: /embed/bundle/{id-or-slug} --- ## Quick Start ### Option 1 -- Script Tag (Floating Widget) Paste this before the closing `` tag: ```html ``` A floating chat button appears in the bottom-right corner. Clicking it opens the chat panel. ### Option 2 -- Script Tag (Inline) Use `data-mode="inline"` to render the chat directly in the page without a floating button. The iframe fills its parent container: ```html

``` ### Option 3 -- Direct iframe For full control over placement, embed the chat directly as an iframe: ```html ``` --- ## Implementation Examples ### Plain HTML -- Product Chat ```html My Product Page

AI Web Scraper

Try the tool right here:

``` ### Plain HTML -- Workflow Chat (Floating Widget) ```html ``` ### React or Next.js -- Product Chat **Option A -- Next.js Script component:** ```tsx return (

AI Web Scraper

[Script src="https://www.agentpmt.com/embed.js" id="web-scraper" color="#3b82f6" position="bottom-right" strategy="lazyOnload"]

); } ``` **Option B -- useEffect (any React app):** ```tsx useEffect(() => { const script = document.createElement("script"); script.src = "https://www.agentpmt.com/embed.js"; script.setAttribute("data-product-id", productId); script.setAttribute("data-accent-color", "#3b82f6"); script.setAttribute("data-position", "bottom-right"); document.body.appendChild(script); return () => { document.body.removeChild(script); const container = document.getElementById("agentpmt-embed-container"); if (container) container.remove(); }; }, [productId]); return null; } ``` ### React or Next.js -- Inline iframe ```tsx const src = `https://www.agentpmt.com/embed/${workflowId}?accent-color=%233b82f6&theme=light`; return ( ``` --- ## Configuration All parameters use kebab-case and work identically whether passed as `data-` attributes on the script tag or as query parameters on a direct iframe URL. | Parameter | Script Attribute | Description | Default | |-----------|-----------------|-------------|---------| | Scope (required -- pick one) | | | | | `product-id` | `data-product-id` | Product ID or slug. Single-tool chat. | -- | | `workflow-id` | `data-workflow-id` | Workflow ID or slug. Multi-step workflow chat. | -- | | `bundle-id` | `data-bundle-id` | Bundle ID or slug. Multi-tool bundle chat. | -- | | Appearance | | | | | `accent-color` | `data-accent-color` | Brand color (hex) for the widget button, chat border, glow, and send button. | `#22c55e` | | `theme` | -- | `light` or `dark`. | `light` | | Agent | | | | | `agent-name` | `data-agent-name` | Override the AI agent's display name. | `Waffles` | | `agent-subtitle` | `data-agent-subtitle` | Text under the agent name. Omit to hide. | `SuperAgent` | | Layout | | | | | `position` | `data-position` | Widget position: `bottom-right` or `bottom-left`. Script tag only. | `bottom-right` | | `mode` | `data-mode` | `widget` (floating button + popup) or `inline` (fills parent container). Script tag only. | `widget` | | `show-scope` | `data-show-scope` | Set to `true` to show the workflow/product scope card. | Hidden | | `budget-id` | -- | Pre-select a specific budget (for multi-budget users). | Auto-detected | > WARNING: One scope required > > You must set exactly one of `product-id`, `workflow-id`, or `bundle-id`. If none is set, the script will not initialize. If you want the dashboard widget instead of chat, use `data-embed-type="dashboard"` (see the [Dashboard Widget guide](/docs/embedded-widgets/embed-the-agentpmt-dashboard-widget)). > WARNING: URL-encode the hash > > When passing hex colors as query parameters, the `#` must be URL-encoded as `%23`. For example, `#3b82f6` becomes `%233b82f6`. --- ## Authentication Flow The chat widget handles authentication automatically. No tokens or API keys need to be passed in by the host page. 1. **User opens the chat widget** The widget checks for an existing session. If none is found, it shows a registration form. 2. **User registers or logs in** New users enter their email and password, then verify via a one-time code sent to their email. Returning users log in with email and password. 3. **Session is established** The user stays signed in for 7 days. No further login is needed during that period. 4. **Budget is resolved** The widget automatically connects the user to their budget so tools can be used. All usage costs are billed to the user's AgentPMT account. --- ## Requirements and Provisioning Flow After authentication, the widget checks whether the scoped tools are ready to use. If not, it guides the user through setup before starting the chat. 1. **Check tool availability** The widget checks if the scoped product(s) or workflow(s) are already on the user's budget. 2. **Add tools to budget (if needed)** If tools are missing, the widget shows an "Add to Budget" prompt. The user confirms, and the tools are added. 3. **Configure credentials (if needed)** If any tool requires API keys, OAuth tokens, or other credentials, the widget shows a credential setup form. The user enters the required values and they are securely stored. 4. **Chat is ready** Once all tools are on the budget and all credentials are configured, the chat interface loads and the user can start talking to the AI agent. > TIP: Automatic re-checking > > If a user adds a tool or configures credentials mid-conversation (via in-chat cards), the widget automatically re-checks requirements and continues the conversation. --- ## Embed Scope Reference ### Product Embed Scopes the chat to a single product (tool). The AI agent can only call that product's tool. **URL:** `https://www.agentpmt.com/embed/product/{productId}` ```html ``` The `productId` can be an ID or a URL-friendly slug from your AgentPMT dashboard. ### Workflow Embed Scopes the chat to a workflow (a chain of tools that run in sequence). The AI agent follows the workflow steps and calls the required tools automatically. **URL:** `https://www.agentpmt.com/embed/{workflowId}` ```html ``` ### Bundle Embed Scopes the chat to a bundle -- a curated collection of products and workflows. The AI agent has access to all tools and workflows in the bundle. **URL:** `https://www.agentpmt.com/embed/bundle/{bundleId}` ```html ``` --- ## Chat Features - **Scoped Tools**: AI agent only accesses tools within the embed scope - **Auto-Provisioning**: Walks users through adding tools and credentials - **Usage Billing**: All tool and agent costs pass through to the end user's account - **In-Chat Cards**: Interactive cards for tool setup and credential entry - **Streaming Responses**: Real-time streaming for instant feedback - **Session Persistence**: Conversations persist across page reloads --- ## Theming ### Light and Dark Mode Use the `theme` parameter to match your site: ### Light (default) ```html ``` ### Dark ```html ``` ### Accent Color The accent color controls the chat shell's border, glow effects, send button, action buttons, and the floating widget button. Pass any hex color to match your brand: ```html ``` --- ## Integration Checklist 1. **Choose your embed type** Decide whether you are embedding a product, workflow, or bundle chat. Get the ID or slug from your AgentPMT dashboard. 2. **Add the embed code** Use a script tag for a floating widget, or an iframe for inline placement. See the examples above. 3. **Set your brand color** Use `data-accent-color` (script tag) or `accent-color` query parameter (iframe) to match your site's primary color. 4. **Test authentication** Open the widget and register a test account. Verify login, logout, and session persistence. 5. **Test tool provisioning** Remove the tool from your test budget, then reopen the chat. Verify the "Add to Budget" prompt appears and works. 6. **Test credential setup** If the tool requires credentials, verify the credential form appears and saves values correctly. 7. **Test the chat** Send a message and verify the AI agent responds and can call the scoped tools. 8. **Test on mobile** Verify the widget is responsive and does not overlap critical mobile UI. --- ## Troubleshooting ### The chat widget does not appear Make sure you have set exactly one of `data-product-id`, `data-workflow-id`, or `data-bundle-id` on the script tag. Without one of these, the script will not initialize. Check the browser console for `[AgentPMT Embed]` error messages. ### The 'Add to Budget' screen keeps appearing This means the tool is not being saved to the user's budget. Check that the product or workflow exists and is active in AgentPMT. If using a slug, verify the slug is correct. ### Credential setup form is empty or shows no fields The tool's software connection may not have credential fields defined. Check the tool's connection configuration in the AgentPMT dashboard. ### Chat messages are lost on page reload Chat sessions are stored server-side and should persist. If messages are lost, check that the session cookie is not being cleared by your site's cookie policy or a browser extension. ### The iframe is blocked or shows a blank page Ensure the `sandbox` attribute includes `allow-scripts allow-same-origin allow-forms`. Also check that your Content Security Policy (CSP) allows `frame-src https://www.agentpmt.com`. --- ## Copy-Paste Starters ### Product Chat (Floating Widget) ```html ``` ### Workflow Chat (Inline iframe) ```html ``` ### Bundle Chat (Dark Theme) ```html ``` --- ## Related Docs - [Embed the Dashboard Widget](/docs/embedded-widgets/embed-the-agentpmt-dashboard-widget) - Let users manage tools, workflows, and budget settings on your site - [What is a Workflow](/docs/core-concepts/what-is-a-workflow) - Learn how workflows chain tools together - [How Credentials Work](/docs/core-concepts/how-credentials-work) - Understand how AgentPMT manages API keys and tokens - [Embed the Crypto Widget](/docs/embedded-widgets/embed-the-agentpmt-crypto-on-off-ramp-widget) - Add a crypto on-off-ramp widget to your site