Widget Agent

A widget agent is a public-facing agent your customers talk to through a chat bubble on your site. Unlike a team agent, it doesn’t appear in your workspace chat — it’s served to visitors on the domains you embed it on, and conversations start anonymous.

Open the Agents tab and click Create an agent.
Choose Widget as the channel.
Give it instructions and tools like any other agent — product lookup, order status, and your automations.

Agents in the list are labeled Widget or Team so you can tell them apart.

Embed it on your website

The agent editor’s Embed section generates a copy-paste snippet for your agent: an iframe pointing at your agent’s widget URL, plus a small script that resizes the frame when the chat opens and closes.

<iframe id="colossal-chat" src="https://<your-workspace-host>/widget/<agent-uid>"
  title="Chat"
  style="position:fixed;bottom:0;right:0;width:112px;height:116px;border:0;background:transparent;color-scheme:light;z-index:2147483000"
></iframe>
<script>
  window.addEventListener("message", function (e) {
    if (!e.data || e.data.type !== "colossal:open-state") return;
    var f = document.getElementById("colossal-chat"), o = e.data.open;
    var full = o && window.innerWidth < 640;
    f.style.width = full ? "100vw" : o ? "400px" : "112px";
    f.style.height = full ? "100dvh" : o ? "min(700px, calc(100dvh - 48px))" : "116px";
  });
</script>

Copy the snippet from the editor rather than hand-writing it — it fills in your agent’s URL and chosen position (bottom-left or bottom-right). Paste it right before the closing </body> tag of your site.

Open the chat from your page

The widget frame accepts two messages from the page that embeds it. Post them once the frame has sent its colossal:widget-ready message.

{ type: "colossal:open" } — opens the chat panel.
{ type: "colossal:send-message", text: "..." } — opens the panel and sends text as the visitor’s message. A message with no text is ignored.

<script>
  var frame = document.getElementById("colossal-chat");
  window.addEventListener("message", function (e) {
    if (!e.data || e.data.type !== "colossal:widget-ready") return;
    document.getElementById("ask-about-shipping").onclick = function () {
      frame.contentWindow.postMessage(
        { type: "colossal:send-message", text: "When will my order ship?" },
        "*"
      );
    };
  });
</script>

Shopify

In the Embed section, switch the target to Shopify before copying. Then in Shopify admin, go to Online Store → Themes → Edit code and paste the snippet before </body> in theme.liquid. The Shopify variant adds two bridges on top of the base snippet:

Sign-in bridge — signs the customer in to the chat using their Shopify login (via the Colossal app proxy), and signs them out when they log out of the store. This requires the Colossal app to be connected to the store; without it, the chat simply stays anonymous and everything else keeps working.
Cart bridge — keeps the storefront cart in sync, so when the agent adds or removes items, the customer’s real Shopify cart updates.

The embedded widget renders product lists, cart updates, and order details out of the box. See Widget components for previews of the built-in components, and for rendering your own UI for automation results — warranty cards, booking confirmations, anything.

Get started

Platform

Agents

Automations

Storefront

Dev Tools

Create a widget agent

Embed it on your website

Open the chat from your page

Shopify

Extending the widget

​Create a widget agent

​Embed it on your website

​Open the chat from your page

​Shopify

​Extending the widget

Create a widget agent

Embed it on your website

Open the chat from your page

Shopify

Extending the widget