Widget Chat

Embed a VeriSwarm-powered chat widget on any website to give your customers direct access to your AI agent. The widget handles authentication, conversation management, and safety controls -- all in a lightweight iframe that drops into your page with a single script tag.

---

Quick Start

Add the embed snippet to your HTML:

<script
  src="https://cdn.veriswarm.ai/widget.js"
  data-agent="your-agent-slug"
  data-token="wtk_your_widget_token"
></script>

The widget appears as a floating chat bubble in the bottom-right corner. Visitors can open it, send messages, and receive responses from your agent in real time.

Get your widget token from the Manage Agent > Settings tab in the dashboard, or generate one via the API.

---

Authentication Modes

Public Mode (Widget Token)

Best for marketing sites, help centers, and public-facing pages where visitors are anonymous.

<script
  src="https://cdn.veriswarm.ai/widget.js"
  data-agent="my-support-agent"
  data-token="wtk_abc123"
  data-greeting="Hi! How can I help you today?"
></script>

The widget token (wtk_...) authenticates the widget itself, not individual users. Configure allowed domains in the dashboard to prevent token misuse on unauthorized origins.

Secure Mode (Session Token)

Best for authenticated areas -- customer portals, dashboards, logged-in experiences -- where you need to tie conversations to a known user.

Step 1: Your backend creates a session

import requests

response = requests.post(
    "https://api.veriswarm.ai/v1/agents/widget/session",
    headers={"x-api-key": "vsk_your_workspace_key"},
    json={
        "agent_id": "agt_123",
        "user_id": "usr_456",
        "metadata": {"plan": "pro", "company": "Acme"}
    },
)
session_token = response.json()["session_token"]

Step 2: Pass the session token to the widget

<script
  src="https://cdn.veriswarm.ai/widget.js"
  data-agent="my-support-agent"
  data-session="wss_session_token_here"
></script>

Session tokens are short-lived and scoped to a single user-agent pair. Your backend should generate a new session token on each page load or when the existing token expires.

---

API Endpoints

Public Chat

POST /v1/agents/widget/chat

Send a message to the agent using a widget token. No user identity is attached.

curl -X POST https://api.veriswarm.ai/v1/agents/widget/chat \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "my-support-agent",
    "widget_token": "wtk_abc123",
    "message": "What are your business hours?",
    "conversation_id": "conv_optional"
  }'

Secure Chat

POST /v1/agents/widget/secure-chat

Send a message using a session token. The conversation is tied to the authenticated user.

curl -X POST https://api.veriswarm.ai/v1/agents/widget/secure-chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "wss_session_token",
    "message": "What is the status of my order?",
    "conversation_id": "conv_optional"
  }'

Create Session

POST /v1/agents/widget/session

Generate a short-lived session token for secure mode.

curl -X POST https://api.veriswarm.ai/v1/agents/widget/session \
  -H "x-api-key: vsk_your_workspace_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_123",
    "user_id": "usr_456",
    "metadata": {"plan": "pro"}
  }'

Response:

{
  "session_token": "wss_abc123",
  "expires_at": "2026-03-28T13:00:00Z"
}

---

Configuration

All configuration is done via data-* attributes on the script tag.

Attribute	Required	Default	Description
data-agent	Yes	--	Agent slug
data-token	Public mode	--	Widget token (wtk_...) for public mode
data-session	Secure mode	--	Session token (wss_...) for secure mode
data-color	No	#d4a053	Accent color (hex) for the chat bubble and header
data-position	No	bottom-right	Widget position: bottom-right or bottom-left
data-greeting	No	--	Initial greeting message displayed when the widget opens
data-api	No	https://api.veriswarm.ai	API base URL (override for self-hosted or staging environments)

Example: Full Configuration

<script
  src="https://cdn.veriswarm.ai/widget.js"
  data-agent="my-support-agent"
  data-token="wtk_abc123"
  data-color="#1a73e8"
  data-position="bottom-left"
  data-greeting="Welcome! Ask me anything about our product."
  data-api="https://api.staging.veriswarm.ai"
></script>

---

Security

PII Tokenization

All messages pass through Guard before reaching the agent's LLM. Personally identifiable information (names, emails, phone numbers, addresses) is automatically tokenized with reversible [VS:TYPE:ID] tokens. The agent never sees raw PII in its context window.

Prompt Injection Scanning

Every user message is scanned for prompt injection patterns before processing. Detected attempts are logged as Guard findings and blocked from reaching the agent.

Rate Limiting

Widget endpoints are rate-limited per widget token (public mode) or per session (secure mode). Exceeding limits returns HTTP 429 with Retry-After headers.

SOUL Output Filtering

Agent responses are filtered through the agent's SOUL configuration. Content that violates the agent's defined boundaries, tone, or compliance rules is caught before delivery to the user.

Origin Allowlist

Configure allowed domains in the dashboard under Manage Agent > Settings > Widget. Requests from origins not on the allowlist are rejected. This prevents third parties from embedding your widget token on unauthorized sites.

---

Knowledge Base

The widget uses the same RAG retrieval pipeline as direct API conversations. When a user asks a question:

1. The query is embedded and matched against the agent's knowledge base (uploaded files, crawled URLs)
2. Relevant document chunks are retrieved and injected into the LLM context
3. The agent generates a grounded response with source attribution when applicable

Upload documents or crawl URLs from the Manage Agent > Knowledge Base tab. Changes are reflected in widget conversations immediately.

---

Conversation Logging and Audit Trail

Every widget conversation is recorded:

• Conversation logs are accessible from the Manage Agent > Conversation Logs tab, filterable by date, user, and conversation ID
• Vault audit entries (if Vault is enabled) provide an immutable, hash-chained record of each message exchange
• Guard findings from injection scans or PII detections are linked to the originating conversation

Secure-mode conversations include the user_id and metadata from the session token, making it straightforward to trace conversations back to specific customers.

---

Token Rotation

Widget tokens can be rotated from the Manage Agent > Settings tab or via the API. When you rotate a token:

1. A new wtk_... token is generated
2. The old token continues to work for a 15-minute grace period
3. After the grace period, the old token is rejected

Update your embed snippet with the new token before the grace period expires.

---

Allowed Domains

Configure which domains may use your widget token:

1. Go to Manage Agent > Settings > Widget
2. Add each allowed origin (e.g., https://www.example.com, https://app.example.com)
3. Save

If no domains are configured, the widget accepts requests from any origin. Adding at least one domain activates enforcement -- only listed origins are permitted.

---

Related Docs

• Fleet -- Agent Management -- agent configuration, knowledge base, and conversation logs
• Guard -- PII tokenization, injection scanning, and kill switch
• Cortex -- Runtime -- LLM routing, fallback chains, and cost tracking
• API Reference -- full endpoint details