Skip to main content
Embed your Agent on any website so visitors or team members can chat with it without leaving the page. Choose between a static iframe that’s always visible or a floating modal that opens on click.

Set up the deployment

1

Navigate to your Agent

Go to Agents and select the Agent you want to embed. Click Edit to open the Agent settings.
Agents page showing the list of available Agents
2

Open the Deployments tab

Navigate to the Deployments tab in your Agent’s settings.
Agent settings with the Deployments tab selected
Deployments tab showing embed configuration options
3

Enable embedded chat

Toggle on Enable Embedded Chat Deployment.
Embedded Chat Deployment toggle switched on
4

Add your allowed domains

Click Add Allowed Domain for each website that will embed the Agent. At least one domain is required unless Require Secure Token is on. Enter each site exactly as visitors reach it, like www.example.com; example.com does not cover www.example.com. To allow every subdomain, add *.example.com. IP addresses, localhost, and shared hosting domains such as *.vercel.app or sharepoint.com are not accepted, but a specific site such as contoso.sharepoint.com is.The chat only works inside an iframe or modal on these sites. Opening the embed URL directly in a browser tab, or in a mobile app that loads it as a full page, shows This chat isn’t available here. If your site is itself shown inside another app, such as SharePoint in Microsoft Teams, add that app’s domains too.
Whitelisted domains section with the Add Whitelisted Domain button
5

Require a secure token (optional)

By default, anyone who has the embed URL can chat with your Agent. To restrict access to only your authenticated users, toggle on Require Secure Token.When enabled, the embed URL requires a short-lived authentication token to work. Create this token on your own backend with your Cassidy API key after you authenticate the user. See Restrict access with secure tokens below for setup instructions. If visitors see This chat is unavailable instead of the chat, see Troubleshooting.
Require Secure Token toggle in the embed Basic settings section
6

Set the display name

Enter the Agent Display Name that visitors will see in the embedded chat widget.
Agent Display Name field in the embed configuration
7

Configure the first message

Enter the First Message that greets visitors when they open the chat. Use this to welcome users or prompt them to ask a question.
First Message field for setting the chat greeting
8

Choose the reference mode

Select the appropriate Reference Mode for your use case:
  • Disable References — no citations shown in responses
  • Public Sources Only — only links to publicly accessible sources
  • Include All References (default) — all citations shown, but users need permissions to view private documents
  • Generate Public Links — creates temporary preview links for cited documents. A link works for one hour; after that, visitors can reopen the source from the chat.
Citations only include sources from the Agent’s own Knowledge Base, cited in that visitor’s chat.
Reference Mode dropdown showing the four available options
Generate Public Links can expose sensitive information. Only use this option if your Agent does not have access to private documents.
9

Save your settings

Click Save Settings to apply your configuration.
10

Choose your embed format

In the Embed Code section, choose between two formats:
  • Static IFrame — the chat component is always visible on the page, ideal for support pages or help centers
Static IFrame embed code snippet
Preview of the static iframe embedded chat on a sample website
  • Modal — a floating button that opens the chat as an overlay, best when you want to offer help without taking up permanent space
Modal embed code snippet
Preview of the modal chat overlay on a sample website
11

Add the code to your website

Copy the embed code and paste it into your website’s HTML where you want the chat to appear. If you’re using a website builder, add it to a custom HTML block.
Embed code being added to a website's HTML
Test the embed on a staging environment before deploying to production. Click Preview in Cassidy to see what the embedded chat looks like before publishing. Preview is available to signed-in members of your organization even though Cassidy isn’t one of your allowed domains.

Regenerate your embed URL or modal

If you need to regenerate the current embed credentials (for example, when you suspect they may have been exposed), click the Regenerate Embed Url/Key button. This will create a new embed key or URL and immediately invalidate all existing chats using the old one.
Preview of the modal chat overlay on a sample website
Preview of the modal chat overlay on a sample website

Bot verification

Every embedded Agent uses Cloudflare Turnstile to check that each visitor is a person, not a bot. Most visitors never notice it; some see a short Verify you are human checkbox at the bottom of the chat. Bot verification protects your Agent, its Knowledge Base, and your credits, so you can’t turn it off.
For embeds behind your own login, use Require Secure Token, which skips the Turnstile check.

Troubleshoot bot verification

Visitors who fail verification see We couldn’t verify your browser instead of the chat.
Networks that inspect secure traffic, such as Netskope or Zscaler, can break the check. Ask IT to allow challenges.cloudflare.com and *.challenges.cloudflare.com, exclude them from SSL/TLS inspection, and allow app.cassidyai.com.
Make the iframe at least 300 pixels wide, and make sure nothing covers its bottom edge, such as a sticky footer or cookie banner.
Ask them to reload the page, allow challenges.cloudflare.com in their ad blocker, or try another browser or network.
Still blocked? Contact support@cassidyai.com.

Restrict access with secure tokens

Without a secure token, an embedded Agent is public on your allowed domains: any visitor to those sites can chat with it. Only your allowed domains can display the chat in an iframe, and each visitor’s browser is verified automatically with bot verification. These checks rely on the visitor’s browser, so they deter misuse but are not authentication. To allow only your authenticated users to chat, enable Require Secure Token. With secure tokens enabled, every embedded chat request must include a short-lived token. Your backend mints that token using your Cassidy API key.
Never put your Cassidy API key in frontend code. Mint tokens only from your backend, then pass the resulting token to the frontend page.
1

Authenticate your user

Use your own login system to confirm the visitor is allowed to use the Agent.
2

Create a backend endpoint that mints tokens

From your backend, call the embed token endpoint with your Cassidy API key. Tokens last at most 1 hour. Longer requested lifetimes are capped, and expires_at reports the actual expiry.
Return the token to your frontend.
3

Pass the token to the embed

  • Static iframe — append the token to the embed URL as a fragment (#token=...). The embed reads the token from the URL when it loads. Your app is responsible for refreshing tokens before they expire — mint a new token from your backend and update the iframe src with the new fragment.
  • Modal — fetch a token from your backend after authenticating the user, then pass it to Cassidy.initialize as authToken. Your app is responsible for refreshing tokens before they expire.

Troubleshooting

If the embed can’t load, visitors see one of these screens instead of the chat.
Screenshot needed: embedded chat showing the “This chat is unavailable” screen
This chat is unavailable The deployment is turned off or the key is wrong, or the embed’s access check failed. With Require Secure Token, this usually means the token was missing, expired, or not passed correctly. Common causes:
  • The embed code on your website does not include a token. For example, the iframe URL is missing #token=..., or the modal was initialized without authToken.
  • The token expired and your site has not refreshed it yet.
  • Your backend is not minting tokens correctly, or the token was created for a different deployment key.
This chat isn’t available here The chat was opened directly instead of inside your website, or from a site that isn’t in Allowed Domains. Allowed domains match exactly: example.com doesn’t include www.example.com. Add each site that shows the chat, or add *.example.com to include every subdomain. If the chat runs inside another app, such as SharePoint in Microsoft Teams, add that app’s domains too. We couldn’t verify your browser The visitor didn’t pass bot verification. A browser extension, ad blocker, company network, or an iframe that hides the checkbox can stop the check. See Troubleshoot bot verification. What to do:
  • If you copied embed code from Cassidy before setting up secure tokens or allowed domains, update your website with the latest embed instructions above.
  • Ask whoever manages your website to confirm the site’s exact domain is listed, and that tokens are being created on your backend and passed into the embed.
  • Try reloading the page. If the error persists, contact your site administrator or Cassidy support.

Pass hidden context to your Agent

Your website can share details about the current visitor, such as their email address, so they don’t have to type them. Add an injected_message parameter to the static iframe URL. The Agent receives this text with every message, but the visitor never sees it in the chat.
URL-encode the value, and keep it under 4,000 characters. If you also use a secure token, keep the #token=... fragment at the end of the URL, after injected_message. For example, a support Agent that files tickets can read the email address and create the ticket for the right person without asking.
Anyone who can open the embed URL can change injected_message. Cassidy doesn’t verify it, so don’t rely on it for identity checks or to control access to sensitive data.

Next steps

Agents overview

Learn more about creating and configuring Agents.

Deploy via email

Deploy your Agent to a dedicated email address.

Deploy via API

Build a custom integration using the Cassidy Agents API.