​

Embedding Agents as Widgets

​

How widgets work

1. Authenticates a guest against a specific agent
2. Receives a guest chat token
3. Uploads files if needed
4. Creates a widget chat task
5. Continues the session over the public chat runtime

​

Agent-level widget controls

• widget_enabled
• allowed_domains

​

Domain allowlist

• Exact domains
• Subdomains
• * for unrestricted access, only if you deliberately want that behavior

​

Recommended setup

• Use a focused prompt
• Keep tools narrow and predictable
• Add safe suggested prompts
• Restrict allowed domains
• Test guest file uploads and session continuity

​

Opening the chat from your page

​

Example

<button id="ask-pricing">Ask about pricing</button>
<button id="open-chat">Chat with us</button>

<script src="https://YOUR_XAGENT_HOST/widget.js" data-widget-key="YOUR_WIDGET_KEY"></script>
<script>
  document.getElementById("ask-pricing").addEventListener("click", function () {
    XagentWidget.open({ message: "What are your pricing plans?" });
  });

  document.getElementById("open-chat").addEventListener("click", function () {
    XagentWidget.open();
  });
</script>

​

Calling XagentWidget.open

XagentWidget.open(options)

• message (string, optional): the text to send as the first message of a new conversation.

• XagentWidget.open() opens the chat panel and sends nothing.
• XagentWidget.open({ message }) opens the chat panel and starts a new conversation. If a conversation is already in progress, it is left behind and the new conversation starts instead. message is sent as the first message of the new conversation, and the agent starts answering it.
• Every call takes effect, including when the panel is already open. The panel does not need to be closed first. If a visitor clicks a second button while the chat is open, the panel stays open and the second message starts another new conversation. Calls that arrive close together are covered under “Repeated and overlapping calls” below.

​

Message rules

Xagent Widget: XagentWidget.open() message must be a non-empty string of at most 2000 characters; opening the chat without sending it.

​

Repeated and overlapping calls

• Each call with a valid message starts a new conversation. The conversation that was replaced is not stopped: if the agent was still answering in it, the answer is completed in the background. The visitor cannot return to the earlier conversation from the chat panel.
• Each call with a valid message also starts a new agent run, which counts toward usage in the same way as a conversation the visitor starts in the panel. The widget itself does not limit how often open can be called.
• If the chat has not finished loading, the message is held and sent as soon as the chat is ready. When several calls are made before that, only the last message is sent.
• If the chat is busy, for example because an earlier call is still starting its conversation or a message the visitor typed is still being sent, the message waits for its turn. Only one message can wait. A newer call replaces the one that is waiting, so when a visitor clicks several buttons quickly, the messages in between are skipped.
• open does not retry a message. If the chat cannot start the new conversation or cannot deliver the message, the message is dropped. The chat then shows the same error notice it shows when the visitor’s own attempt fails in the same way, and a warning is written to the browser console.
• Starting a new conversation discards any text the visitor typed into the chat input but did not send.
• After open has been called with a valid message, that widget no longer sends the message set with its data-initial-message attribute. Calling open without a message leaves it unchanged. If the widget had already sent the data-initial-message text to the chat, for example because the panel opened a moment earlier or open() was called without a message just before, that text is not withdrawn: the chat starts a conversation with it as usual, and the message from open then starts a new conversation that replaces it.
• If the page has more than one widget, the call goes to the most recently initialized one that is still on the page.

​

Widget vs share link

• The agent is embedded into your product or site
• You need origin checks
• The conversation is part of a product experience

• You want a public standalone entry point
• The interaction is link-driven rather than embedded

​

Related pages

• Sharing Agents
• Building Agents
• API Reference: Widget Endpoints