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.

2
Open the Deployments tab
Navigate to the Deployments tab in your Agent’s settings.



3
Enable embedded chat
Toggle on Enable Embedded Chat Deployment.

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.
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.

6
Set the display name
Enter the Agent Display Name that visitors will see in the embedded chat widget.

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.

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.

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


- Modal — a floating button that opens the chat as an overlay, best when you want to offer help without taking up permanent space


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.

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.

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.Troubleshoot bot verification
Visitors who fail verification see We couldn’t verify your browser instead of the chat.Visitors on a company network or VPN are blocked
Visitors on a company network or VPN are blocked
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.The checkbox is cut off or can't be clicked
The checkbox is cut off or can't be clicked
Make the iframe at least 300 pixels wide, and make sure nothing covers its
bottom edge, such as a sticky footer or cookie banner.
A single visitor is blocked
A single visitor is blocked
Ask them to reload the page, allow
challenges.cloudflare.com in their ad
blocker, or try another browser or network.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.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 Return the token to your frontend.
expires_at reports the actual expiry.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 iframesrcwith the new fragment.
- Modal — fetch a token from your backend after authenticating the user, then pass it to
Cassidy.initializeasauthToken. 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
- The embed code on your website does not include a token. For example, the iframe URL is missing
#token=..., or the modal was initialized withoutauthToken. - 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.
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 aninjected_message parameter to the static iframe URL. The Agent receives this text with every message, but the visitor never sees it in the chat.
#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.
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.