Skip to main content
Deploy a Brand Agent to your website when you want visitors to ask questions, get product guidance, or submit lead details. This creates a public website chat widget backed by your Brand Agent knowledge and approved tools. Use this guide for copy-paste website embeds. If you are building a custom product integration or calling your agent from code, use the Public API instead.

​
Before You Start

You need:
  • A created Brand Agent
  • A tested customer-facing conversation flow
  • A published version of the agent
  • Widget styling reviewed
Most website embeds use a public agent. A public widget requests short-lived authorization scoped to that one agent, so no long-lived credential sits in your page source. You can also embed a private agent by adding a scoped runtime key to the snippet. See Embed a Private Agent.

​
Website access restrictions

By default, a public Brand Agent has no domain restrictions and its widget can be embedded on any website. Add an allowlist when the widget should run only on sites you control:
  1. Open your Brand Agent’s Publish or Embed settings.
  2. Under Website access, enter a hostname such as example.com or a website URL, then select Add.
  3. Add up to 25 domains. Use *.example.com to allow example.com and its subdomains.
  4. Remove any domain that should no longer load the widget, then select Save.
The allowlist checks the embedding page’s HTTP or HTTPS hostname. Paths are not stored as separate rules, and a hostname that is not listed cannot load the restricted widget. If the widget is missing after you save the list, check that the page hostname matches an entry, including the correct subdomain or wildcard, and confirm that the Brand Agent is still public and published. Saving one or more allowed domains disables the Fullscreen iframe option. Use the chat bubble or floating pill embed while the widget is restricted, or remove all saved domains before using a fullscreen iframe.

​
Floating Chat Bubble

Use the floating chat bubble when you want the agent available across your site as a website chatbot.
  1. Open your Brand Agent.
  2. Test the agent with realistic visitor questions.
  3. Open Publish.
  4. Choose the chat bubble/widget option.
  5. Copy the embed snippet.
  6. Paste the snippet into your website template, layout, or tag manager.
Example:
For multi-page websites, add the script to your shared layout so the widget appears consistently.

​
Floating Pill Layout

The floating pill is an alternative launcher: a bottom-center pill instead of a corner bubble, with the chat panel opening above it when the visitor sends a message. Add data-layout="floating" to the same script tag.
The floating pill is marked Experimental in the Publish screen. The chat bubble is the stable default; use the pill when the bottom-center placement suits your layout better, and test it on mobile before rolling it out.

​
Embed a Private Agent

A private agent can run on your website when the snippet carries a Teamspace runtime key scoped to that single agent. Use this when the agent should not be reachable by anyone who copies your agent ID.
  1. Open Teamspace settings → API keys → Create key.
  2. Enable Run agents, and scope the key to the one agent and project this website needs.
  3. Open your Brand Agent’s Publish screen and copy the snippet. While the agent is private, the snippet includes a data-api-key placeholder.
  4. Replace the placeholder with your scoped key.
The widget hands the key to the chat frame in memory and exchanges it for short-lived, agent-scoped authorization. It does not persist the key in browser storage.
A key placed in page HTML is still readable by anyone who views the page source. Scope it to the single agent that runs on that site, never reuse a broad Teamspace key, and keep it out of URLs, logs, and cookies. Rotate it by revoking the old key and pasting a new one into the snippet.
Messaging channels such as WhatsApp, Instagram, Telegram, Slack, and Zapier keep working while the agent is private, without a key in any page.

​
How Widget Visitors Are Identified

SketricGen assigns the visitor identity for embedded widgets on the server. When a widget loads, it requests authorization for the agent, and SketricGen mints the contact identity and a visitor credential for that browser. A returning visitor presents the stored credential and continues their previous identity, so repeat conversations stay grouped without any work on your page.
The widget does not accept a visitor identity chosen by the page. data-contact-id on the embed script, and the contactId query parameter on iframe and fullscreen URLs, are ignored for browser embeds. Because conversations are keyed by contact, a page-supplied identifier would let any site claim to be one of your known contacts.
To tie conversations to your own user records, call the Runtime API from your backend and send contact_id in the request body. That path is authenticated with a Teamspace runtime key, so the identifier can be trusted.

​
Inline iFrame

Use an iframe when you want the agent embedded directly inside a page section.
The Fullscreen iframe option appears in the Publish screen only while the agent is public and no Website access domains are saved. Use the chat bubble or floating pill for a private or domain-restricted embed.
  1. Open your Brand Agent.
  2. Open Publish.
  3. Choose Fullscreen iframe.
  4. Copy the iframe code.
  5. Paste it into the page where the chat should appear.
The Publish screen generates a /fullscreen-widget/ URL:
/iframe-widget/YOUR_AGENT_ID serves the same chat interface and is the better fit when the agent sits inside a page section rather than filling it.

​
Test After Deploying

After adding the widget:
  1. Open the live page.
  2. Confirm the widget or iframe appears.
  3. Ask a question from your Brand Agent’s Knowledge Base.
  4. Reload the page and confirm the previous conversation is still available to the same browser.
  5. Test lead capture if enabled.
  6. Check the conversation in SketricGen.
If the widget does not appear, confirm the Brand Agent is published, that the data-agent-id or iframe URL uses the correct agent ID, and that the page hostname matches your Website access list. For a private agent, also confirm the snippet carries a valid data-api-key.