Embed Widget

Embeddable Chat Widget

Add a privacy-first AI chat to any website with a single script tag. User messages are scanned for PII and automatically redacted before reaching the AI model.

Quick Start

Get the chat widget running on your site in three steps.

Generate your API key

Sign in and use the key manager below in the API Keys section to generate a key instantly. Keys use the pk_ prefix (public key convention) and are safe to include in client-side code.

Add the script tag

Paste the following snippet before the closing </body> tag on any page where you want the chat widget:

<script
  src="https://your-app.privaishield.com/embed/embed.js"
  data-api-key="pk_your_api_key"
  data-model="claude-sonnet"
  data-theme="dark"
  data-position="bottom-right">
</script>

You're done

A floating shield button appears in the corner of your page. When users click it, a chat panel opens. All messages are scanned for PII and redacted before being sent to the AI model.

Configuration Options

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

Attribute	Required	Default	Description
data-api-key	Yes	—	Your PrivaiShield API key (starts with `pk_`)
data-model	No	claude-sonnet	AI model to use: `gpt-4o`, `claude-sonnet`, or `gemini-pro`
data-theme	No	dark	Widget color theme: `dark` or `light`
data-position	No	bottom-right	Bubble position: `bottom-right`, `bottom-left`, `top-right`, or `top-left`
data-redaction-mode	No	client	Redaction mode: `client` (real-time entity recognition in-browser) or `hybrid` (in-browser + deep learning NER for names and context)
data-store-chat	No	false	Enable server-side chat persistence. When `"true"`, conversations are saved and can be continued across sessions. Users can also toggle this from the cloud icon in the widget header.

API Keys

API keys authenticate requests from your embedded widget to the PrivaiShield backend. Each key is scoped to your account and enables all supported AI models by default.

Security note

API keys with the pk_ prefix are designed to be included in client-side code. They only authorize access to the embed chat endpoint and cannot be used to access other PrivaiShield APIs. Rate limiting is applied per key.

Once you have a key, add it to your embed script tag:

<script src=".../embed.js" data-api-key="pk_your_generated_key"></script>

How It Works

The embed widget uses an iframe-based architecture for security and isolation. Here is the data flow:

1. Loader script creates the bubble

The embed.js script reads configuration from the script tag's data-* attributes and injects a floating button into the host page.

2. Click opens an iframe

The chat UI loads inside an iframe pointing to /embed/widget.html on the PrivaiShield origin. This means all API calls from the widget are same-origin — no CORS issues.

3. PII is detected and redacted

Before sending, the widget scans for PII. In client mode, 19+ entity types (emails, SSNs, phones, addresses, and more) are detected in real time. In hybrid mode, AI-powered detection also catches names and context-dependent data. Entities are replaced with tokens (e.g., [EMAIL_1]). The user sees a redaction summary inline.

4. Redacted text is sent to the AI

The sanitized message is sent to POST /api/embed/chat with the API key in the X-API-Key header. The server validates the key, calls the selected AI model, and returns the response.

Chat Storage

By default, embed widget conversations are ephemeral — they exist only in the browser tab and are lost when the page is closed. You can enable server-side chat persistence so conversations are saved and can be continued later.

Enabling chat storage

There are two ways to enable it:

Via script attribute

Set data-store-chat="true" on the embed script tag to enable storage by default for all users.

<script src=".../embed.js"
  data-api-key="pk_..."
  data-store-chat="true">
</script>

Via widget toggle

Users can click the cloud icon in the widget header to toggle chat storage on or off at any time. A green icon indicates storage is active.

OffOn

How storage works

When enabled, each message exchange is saved server-side. The API returns a sessionId that the widget uses to continue the conversation. Only redacted (PII-free) messages are stored — your original text is never persisted. Stored sessions are encrypted with AES-256-GCM using AWS KMS.

Supported Models

GPT-4o

gpt-4o

OpenAI

Multimodal flagship model with strong general reasoning.

Claude Sonnet

claude-sonnet

Anthropic

Fast and capable model with excellent instruction following.

Gemini Pro

gemini-pro

Google

Google's Gemini 2.0 Flash for fast, efficient responses.

Set the model via the data-model attribute. API keys can be configured to restrict which models a client can access.

Theming

The widget ships with two built-in themes. Set the theme via the data-theme attribute on the script tag.

Dark theme

Default. Dark backgrounds with indigo accents. Matches the browser extension overlay.

Light theme

Light backgrounds for sites with light color schemes. Same indigo accent.

<!-- Dark theme (default) -->
<script src=".../embed.js" data-api-key="pk_..." data-theme="dark"></script>

<!-- Light theme -->
<script src=".../embed.js" data-api-key="pk_..." data-theme="light"></script>

PII Detection

The widget includes the PrivaiShield entity recognition engine. In client mode, 19+ entity types are detected in real time within the user's browser. In hybrid mode, deep learning\u2013powered NER on the server adds coverage for names and context-dependent entities.

Detected entity types

Type	Example	Replacement
SSN	123-45-6789	[SSN_1]
EMAIL	john@example.com	[EMAIL_1]
PHONE	555-123-4567	[PHONE_1]
FINANCIAL	****1234	[FINANCIAL_1]
DOB	DOB: 03/15/1990	[DOB_1]
IP_ADDRESS	192.168.1.1	[IP_ADDRESS_1]
ADDRESS	123 Main St, Boston, MA 02101	[ADDRESS_1]
API_KEY	sk-live-abc123...	[API_KEY_1]
ACCOUNT_NUMBER	Account: 7291038	[ACCOUNT_NUMBER_1]
EIN	EIN: 12-3456789	[EIN_1]

Plus: MRN, SSH keys, AWS instance IDs, insurance policy numbers, account IDs, case numbers, and ticket numbers.

API Reference

The embed widget communicates with the following endpoint. You can also call it directly for custom integrations.

POST/api/embed/chat

Headers

Content-Type: application/json
X-API-Key: pk_your_api_key

Request body

{
  "model": "claude-sonnet",
  "messages": [
    { "role": "user", "content": "Hello, how are you?" }
  ],
  "redactionMode": "hybrid",
  "storeChat": true,
  "sessionId": "optional-existing-session-id"
}

redactionMode is optional. Use "client" (default) for in-browser detection or "hybrid" for in-browser + deep learning NER.

storeChat (optional, boolean) — set to true to persist the conversation on the server. When enabled, the response includes a sessionId you can pass in subsequent requests to continue the same conversation.

sessionId (optional, string) — pass a previously returned session ID to append messages to an existing conversation. Requires storeChat: true.

Successful response (200)

{
  "content": "Hello! I'm doing well. How can I help you today?",
  "sessionId": "abc123-def456"
}

Error response (401 / 400 / 403 / 500)

{
  "error": "Invalid or missing API key"
}

cURL example

curl -X POST https://<your-privaishield-domain>/api/embed/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_your_api_key" \
  -d '{
    "model": "claude-sonnet",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Troubleshooting

The bubble doesn't appear on my page

Make sure the script tag has a valid src pointing to your PrivaiShield instance's /embed/embed.js path. Check the browser console for errors. The data-api-key attribute is required.

I get a 401 "Invalid or missing API key" error

Verify your API key starts with pk_ and was generated from the API Keys section above. If using a manually configured key, check the server's EMBED_API_KEYS environment variable.

I get a 403 "Model not allowed" error

Your API key may be restricted to specific models. Self-service keys enable all models by default. Manually configured keys may have model restrictions.

The widget loads but chat doesn't work (network error)

The widget.html page must be served from the same origin as the /api/embed/chat endpoint. If you're self-hosting, ensure the built files are in the public/embed/ directory of your Next.js app.

PII is not being detected in my messages

In client mode, the entity recognition engine detects structured PII formats (SSN: XXX-XX-XXXX, emails, phone numbers, etc.). For names and context-dependent data, switch to hybrid mode which adds deep learning–powered NER.

Ready to get started?

Try the interactive demo to see PII redaction in action, or generate an API key above to add the widget to your site.

Try the Demo View Pricing