# Embed the AgentPMT Chat Widget > Developer guide for embedding AgentPMT scoped chat on your site. Supports product, workflow, and agent iframe embeds, plus script-based product, workflow, and bundle widgets. 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 approved tools and workflows -- 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**, **agent**, or preconfigured **bundle**. When a user opens the chat: 1. They register or sign in inside the embed 2. AgentPMT checks the scoped tools, Agent Group access, and credential requirements 3. If setup is needed, the chat can show action cards for enabling tools or configuring credentials 4. Once the user is authenticated and the scope is ready, the AI agent can chat and call the approved tools 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 Use a direct iframe for the most explicit integration. Use the script tag when you want AgentPMT to create a floating widget or inline iframe for you. - [Product](#product-embed) - Single-tool chat. URL: /embed/product/{id-or-slug} - [Workflow](#workflow-embed) - Workflow-scoped chat. URL: /embed/{id-or-slug} - [Agent](#agent-embed) - A built agent with its attached tools and workflows. URL: /embed/agent/{id-or-slug} - [Bundle](#bundle-embed) - A preconfigured group of 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 -- Agent iframe ```tsx const src = `https://www.agentpmt.com/embed/agent/${agentId}?accent-color=%233b82f6&theme=light`; return ( ``` --- ## Configuration Script attributes and iframe query parameters overlap, but they are not identical. Use `data-` attributes on the script tag; use query parameters on direct iframe URLs. | Parameter | Script Attribute | Iframe Query | Description | Default | |-----------|-----------------|--------------|-------------|---------| | Scope (script tag -- pick one) | | | | | | `product-id` | `data-product-id` | -- | Product ID or slug. Single-tool chat. | -- | | `workflow-id` | `data-workflow-id` | -- | Workflow ID or slug. Workflow-scoped chat. | -- | | `bundle-id` | `data-bundle-id` | -- | Bundle ID or slug. Preconfigured grouped chat. | -- | | Scope (direct iframe path) | | | | | | Product path | -- | `/embed/product/{id-or-slug}` | Product-scoped iframe. | -- | | Workflow path | -- | `/embed/{id-or-slug}` | Workflow-scoped iframe. | -- | | Agent path | -- | `/embed/agent/{id-or-slug}` | Agent-scoped iframe. | -- | | Bundle path | -- | `/embed/bundle/{id-or-slug}` | Bundle-scoped iframe. | -- | | Appearance | | | | | | `accent-color` | `data-accent-color` | `accent-color` | Brand color (hex) for the widget button, chat border, glow, and send button. | `#22c55e` | | `theme` | -- | `theme` | `light` or `dark`. | `light` | | Agent display | | | | | | `agent-name` | `data-agent-name` | `agent-name` | Override the AI agent's display name. | `Waffles` | | `agent-subtitle` | `data-agent-subtitle` | `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` | `show-scope` | Set to `true` to show the workflow/product/agent scope card. | Hidden | > WARNING: One script scope required > > For script-tag embeds, set exactly one of `data-product-id`, `data-workflow-id`, or `data-bundle-id`. If none is set, the script will not initialize. For Agent embeds, use a direct iframe URL under `/embed/agent/{id-or-slug}`. > 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, then verify via a one-time code sent to their email. Returning users log in inside the embed. 3. **Session is established** The user stays signed in for the embed session. No host-page token is required. 4. **Agent Group access is resolved** AgentPMT connects the signed-in user to the relevant Agent Group context so scoped tools can be used and activity can be logged. --- ## Requirements and Setup Flow After authentication, AgentPMT checks whether the scoped tools are ready to use. If setup is needed, the user handles it through chat cards or the dashboard. 1. **Check tool availability** AgentPMT checks whether the scoped product, workflow, agent, or bundle can run for the user's Agent Group. 2. **Enable missing tools if needed** If scoped tools are missing from the Agent Group, the chat can show a setup card so the user can confirm the change. 3. **Configure credentials if needed** If any tool requires API keys, OAuth tokens, or other credentials, the chat can show a credential setup card. Secret values are stored by AgentPMT and injected server-side. 4. **Chat is ready** Once access and credentials are ready, the user can chat with the scoped AI agent. > TIP: Automatic re-checking > > If a user enables a tool or configures credentials mid-conversation, the widget 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. ### Workflow Embed Scopes the chat to a workflow. The AI agent follows the workflow context and calls required tools automatically. **URL:** `https://www.agentpmt.com/embed/{workflowId}` ```html ``` ### Agent Embed Scopes the chat to a built AgentPMT agent and the tools and workflows attached to that agent. **URL:** `https://www.agentpmt.com/embed/agent/{agentId}` ```html ``` ### Bundle Embed Scopes the chat to a preconfigured bundle -- a curated collection of products and workflows. **URL:** `https://www.agentpmt.com/embed/bundle/{bundleId}` ```html ``` --- ## Chat Features - **Scoped Tools**: AI agent only accesses tools within the embed scope - **Setup Cards**: Guides users through enabling tools and configuring credentials when needed - **Usage Billing**: All tool and agent costs pass through to the end user's account - **Credential Cards**: Interactive setup cards for credential entry and OAuth flows - **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, agent, or bundle chat. Get the ID or slug from AgentPMT. 2. **Add the embed code** Use a script tag for a floating widget, or an iframe for inline placement. Use a direct iframe for Agent embeds. 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 setup cards** Try the embed with a user whose Agent Group does not already include the scoped tools. Verify the setup card appears and the confirmed change is saved. 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 For script-tag embeds, make sure you have set exactly one of `data-product-id`, `data-workflow-id`, or `data-bundle-id`. Without one of these, the script will not initialize. Check the browser console for `[AgentPMT Embed]` error messages. ### A setup card keeps appearing This usually means the scoped tool or workflow is not being saved to the user's Agent Group, or the user does not have access to the scoped item. Verify the item exists, is active, and can be enabled for that user. ### 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 AgentPMT. ### 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 ``` ### Agent Chat (Inline iframe) ```html ``` --- ## Related Docs - [Embed the Dashboard Widget](/docs/embedded-widgets/embed-the-agentpmt-dashboard-widget) - Let users manage tools, workflows, and Agent Group 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