Deploy via embed

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

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

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

Enable embedded chat

Toggle on Enable Embedded Chat Deployment.

Embedded Chat Deployment toggle switched on

Whitelist your domains

Click Add Whitelisted Domain to specify which website domains are allowed to embed the Agent. You can add multiple domains and remove them as needed.

Whitelisted domains section with the Add Whitelisted Domain button

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 an Unauthorized error instead of the chat, see Troubleshooting.

Require Secure Token toggle in the embed Basic settings section

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

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

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 public URLs for cited documents

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.

Save your settings

Click Save Settings to apply your configuration.

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

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

Preview of the modal chat overlay on a sample website

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.

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.

Restrict access with secure tokens

By default, an embedded Agent is public. Anyone with the embed URL can chat with it. Whitelisted domains only control which sites may visually embed the iframe in a browser; they do not stop someone who has the URL from opening it directly. 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.

Authenticate your user

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

Create a backend endpoint that mints tokens

From your backend, call the embed token endpoint with your Cassidy API key. The token defaults to a 1-hour lifetime, with a 7-day maximum.

const response = await fetch("https://app.cassidyai.com/api/assistants/embed/token/create", {
  method: "POST",
  headers: {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    deployment_key: "YOUR_DEPLOYMENT_KEY",
    expires_in_seconds: 3600
  })
})

const { token, expires_at } = await response.json()

Return the token to your frontend.

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.

<iframe
  src="https://app.cassidyai.com/embed/chat/v2/YOUR_DEPLOYMENT_KEY#token=YOUR_GENERATED_TOKEN"
  style="border: none; height: 500px; width: 600px"
  allow="clipboard-read; clipboard-write"
></iframe>

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.

<script src="https://unpkg.com/@cassidyai/chat-deployment@latest/dist"></script>
<script>
  (async () => {
    const res = await fetch("/your-backend/cassidy-embed-token")
    const { token } = await res.json()

    Cassidy.initialize({
      key: "YOUR_DEPLOYMENT_KEY",
      baseUrl: "https://app.cassidyai.com",
      authToken: token,
    })
  })()
</script>

Troubleshooting

If Require Secure Token is enabled and the embed does not receive a valid token, visitors will see an Unauthorized screen instead of the chat. This means the embed is working, but 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.

What to do:

If you copied embed code from Cassidy before setting up secure tokens, update your website with the latest embed instructions above.
Ask whoever manages your website to confirm 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.

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

Getting started

Agents

Workflows

Knowledge Base

Meetings

Extensions

Settings and admin

Security and compliance

Deploy via embed

Set up the deployment

Restrict access with secure tokens

Troubleshooting

Next steps

Agents overview

Deploy via email

Deploy via API

​Set up the deployment

​Regenerate your embed URL or modal

​Restrict access with secure tokens

​Troubleshooting

​Next steps

Agents overview

Deploy via email

Deploy via API

Set up the deployment

Regenerate your embed URL or modal

Restrict access with secure tokens

Troubleshooting

Next steps