How can we help?

Creating your account

Signing up for Cassandra AI is free and takes less than a minute. Head to the Sign Up page and create your account with email and password via Clerk.

After signing up, Clerk will handle email verification automatically. You must verify your email before you can access the dashboard.

Creating your first organization

Once your email is verified, you'll be redirected to the Organization Selection screen. Cassandra AI requires an organization to operate — personal accounts are not supported. This means:

• You must create a new organization or join an existing one before accessing the dashboard.
• Each organization has its own conversations, widget settings, knowledge base, and billing plan.
• You can switch between organizations at any time from the sidebar.

What happens next

After selecting or creating an organization, you'll land on the Conversations page — the heart of Cassandra AI. From here you can:

• Install the chat widget on your website to start capturing leads
• Configure your AI agent's personality and knowledge base
• Customize the widget's appearance to match your brand
• Connect voice AI for phone and web calls

How organizations work

Everything in Cassandra AI is scoped to an organization. Your conversations, widget configuration, uploaded files, billing plan, and integrations all belong to the currently selected organization.

Switching organizations

The Organization Switcher is located in the sidebar header. Click it to see all organizations you belong to, create a new one, or switch to a different workspace. Switching is instant — all dashboard data updates to reflect the selected organization.

Inviting team members

You can invite team members to your organization through Clerk's built-in team management. Each member gets access to the same conversations, settings, and features based on their role.

Organization ID

Every organization has a unique ID used to connect the chat widget to your account. You can find and copy your Organization ID from the Integrations page in the dashboard.

The conversations inbox

The Conversations page is your command center. It uses a three-panel layout:

• Conversations list (left): all chats from your widget, sorted by most recent activity.
• Chat panel (center): the full message thread for the selected conversation.
• Contact panel (right): detailed information about the visitor.

Filtering conversations

Use the status dropdown at the top of the conversations list to filter by:

• All: every conversation regardless of status.
• Unresolved: new or ongoing conversations where the AI is actively responding.
• Escalated: conversations that have been flagged for human attention, either by the AI or manually by an operator.
• Resolved: conversations that have been closed.

Your filter preference is saved in the browser and persisted across sessions.

Conversation details

Each conversation in the list shows:

• An auto-generated avatar (Dicebear) unique to each visitor
• A country flag derived from the visitor's timezone
• The visitor's name and time since creation
• A preview of the last message (with a reply icon if the last message was from an operator)
• A status icon (unresolved, escalated, or resolved)

Conversation statuses

Every conversation goes through a lifecycle:

• Unresolved: the default state. The AI agent handles the conversation automatically.
• Escalated: the conversation needs human attention. The AI stops responding and only operators can reply. This happens automatically when an operator sends a manual message, or when the AI decides to escalate using its built-in tool.
• Resolved: the conversation is closed. The input is disabled in both the widget and the dashboard.

You can change the status manually by clicking the status button in the chat header. The cycle is: Unresolved → Escalated → Resolved → Unresolved.

Replying as an operator

Type your message in the input at the bottom of the chat panel and press Enter to send. When you reply manually to an unresolved conversation, it is automatically escalated — the AI steps aside and lets you handle it from that point.

Contact panel

The right panel shows everything Cassandra captured about the visitor:

• Name and email with a direct "Send Email" button
• Device Information: browser (name + version), OS, device type, screen resolution, viewport size, cookie status
• Location & Language: country (derived from timezone), browser language, timezone, UTC offset
• Session Details: when the session started

How the AI agent works

Cassandra AI uses a GPT-4o powered agent that responds to visitors in real-time. The agent has access to three built-in tools:

• Search: queries your Knowledge Base (RAG) to find relevant information from uploaded documents.
• Escalate: flags the conversation for human review when it can't help or detects a complex issue.
• Resolve: closes the conversation when the visitor's question has been fully answered.

The agent responds automatically to every message in unresolved conversations. Once a conversation is escalated (manually or by the AI), the agent stops responding and only human operators can reply.

AI Persona (Ultimate plan)

Navigate to AI Agent → AI Persona to define your agent's personality with a custom System Prompt. This instruction set is prepended to every conversation, shaping how the AI behaves, what tone it uses, and what it should or shouldn't say.

The system prompt works alongside the agent's built-in tools — your persona instructions add personality without removing the agent's ability to search, escalate, or resolve.

Agent Settings (Pro plan)

Navigate to AI Agent → Agent Settings to configure:

• Escalation Emails: toggle on to receive an email notification when the AI escalates a conversation. You can set a custom email address for these alerts.
• Conversation Starters: define up to 3 suggested questions that appear as clickable chips in the widget after the greeting message. Examples: "What are your pricing plans?", "How do I reset my password?", "Contact support".
• Voice Assistant: (visible only if Vapi is connected) select which Vapi assistant handles voice calls and which phone number to display.

What is the Knowledge Base?

The Knowledge Base is your AI agent's reference library. Upload documents about your product, services, FAQ, or policies, and the agent will search through them to provide accurate, context-aware answers during conversations.

Under the hood, Cassandra uses Retrieval-Augmented Generation (RAG) — uploaded files are processed, indexed, and stored in a searchable namespace unique to your organization. When a visitor asks a question, the AI performs a semantic search across your documents to find the most relevant information.

Uploading files

Navigate to Knowledge Base in the sidebar and click "Add New". Fill in the upload form:

1. Category (required): a label to organize your files (e.g., "Documentation", "Support", "Product").
2. Filename (optional): override the original file name for better organization.
3. File: drag and drop or click to browse.

Supported formats

• PDF (.pdf) — text extracted with GPT-4o for accurate parsing of complex layouts.
• CSV (.csv) — read as plain text, ideal for structured data like FAQ lists.
• TXT (.txt) — read directly, perfect for guides and documentation.
• Images (JPEG, PNG, WebP, GIF) — described and transcribed using GPT-4o-mini, useful for screenshots with text or diagrams.

Managing files

The Knowledge Base page shows a table with all your uploaded files: name, type badge, file size, and actions. You can delete any file through the dropdown menu — this removes it from both the storage and the RAG index. The list supports infinite scroll pagination.

Plan requirement

The Knowledge Base is available on Pro and Ultimate plans. On the Free plan, a feature overlay with plan details will guide you to upgrade.

Overview

The Widget Customization page lets you control every visual and behavioral aspect of your chat widget. It features a two-column layout: the settings form on the left and a live widget preview (iframe) on the right that updates in real-time as you make changes.

Language

Choose the widget's display language. All UI text (buttons, labels, status messages) will be translated automatically. Supported languages:

• English, Italian, German, Spanish, French, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese

Welcome screen

Customize what visitors see when the widget opens:

• Welcome Title: the main heading (e.g., "Welcome to Support").
• Welcome Description: a subtitle with a 120-character limit (e.g., "How can we help you today?").
• Welcome Image: upload a logo or illustration to display in the widget header.

Widget appearance

Upload a Custom Icon to replace the default chat bubble on the floating launcher button. The icon inherits the primary color of your selected theme.

Chat configuration

• AI Agent Icon: upload an avatar that appears next to the AI's messages in the chat.
• Greeting Message: the first message the AI sends when a visitor starts a conversation (e.g., "Hi! How can I help you today?").

Theme

Choose from 17 predefined themes including Default, Zinc, Slate, Stone, Red, Rose, Orange, Green, Blue, Yellow, Violet, and more. Each theme includes:

• A unique color palette (primary, secondary, accent, background)
• A carefully paired Google Font loaded automatically
• Support for light and dark modes via the mode toggle

The theme preview shows a mini widget mockup, hex color codes, and the font name for easy comparison.

Branding

Toggle Remove Branding to hide the "Powered by Cassandra" footer from the widget, giving your customers a fully white-label experience.

How the widget works for visitors

When a visitor lands on your website, they see a floating chat button in the bottom-right corner (or bottom-left, depending on configuration). Clicking it opens the widget in a 400×600px iframe overlay.

Step 1: Authentication

The first screen asks the visitor for their name and email. This information creates a contact session that lasts 24 hours. If the visitor returns within that window, they skip this step and go straight to the menu.

Behind the scenes, Cassandra automatically collects browser metadata: user agent, language, platform, screen resolution, viewport size, timezone, cookie status, referrer URL, and current page URL. This data is visible to operators in the Contact Panel.

Step 2: Selection menu

After authenticating, the visitor sees a menu with up to three options:

• Start chat — always available. Creates a new conversation with the AI agent.
• Start voice call — visible only if Vapi is connected and an assistant is configured. Launches a real-time voice call.
• Call us — visible only if Vapi is connected and a phone number is configured. Shows the phone number with copy and call buttons.

Step 3: Chat

In the chat, the visitor sees the greeting message followed by up to 3 conversation starters (clickable suggestion chips). The AI responds in real-time using the configured persona and knowledge base.

• Messages appear instantly (optimistic rendering) with a typing indicator while the AI generates its response.
• If the conversation is escalated, the visitor can still send messages but only human operators will reply.
• If the conversation is resolved, the input is disabled with a status message.

Inbox

Visitors can access their conversation history through the Inbox icon in the widget footer. This shows all previous conversations with the last message preview, time elapsed, and status indicator. Clicking a conversation reopens it in the chat view.

Voice call

The voice screen provides a real-time voice conversation with the AI assistant powered by Vapi. It includes live transcription, status indicators ("Listening..." or "Assistant Speaking..."), and start/end call buttons.

Contact page

If a phone number is configured, the contact page shows a large phone number, a "Copy number" button with clipboard feedback, and a "Call Now"link that opens the device's phone dialer.

What is Vapi?

Vapi is a voice AI platform that powers real-time voice conversations. By connecting Vapi to Cassandra AI, your visitors can talk to your AI agent via web calls or see a phone number to call directly.

Connecting Vapi

Navigate to Voice Assistant in the sidebar. If Vapi is not yet connected, you'll see a connection card with an overview of features:

• Web voice calls directly from the chat widget
• Phone number support for inbound calls
• Outbound call capabilities
• Workflow automation

Click "Connect" and enter your Vapi API keys:

1. Public API Key — used for client-side voice connections.
2. Private API Key — used for server-side operations (fetching assistants, phone numbers).

Managing your Vapi account

Once connected, the Vapi page shows:

• Phone Numbers tab: a table of all phone numbers from your Vapi account, showing number, name, and active status.
• AI Assistants tab: a table of all assistants, showing name, model, and first message.

Configuring voice in the widget

After connecting Vapi, go to AI Agent → Agent Settings to select:

• Voice Assistant: which Vapi assistant handles web voice calls.
• Display Phone Number: which phone number is shown in the widget's contact page.

If an assistant is selected, the "Start voice call" option appears in the widget. If a phone number is selected, the "Call us" option appears. Both are independent — you can enable one, both, or neither.

Disconnecting

Click the red "Disconnect" button on the Vapi page and confirm in the dialog. This removes your API keys and disables voice features in the widget. You can reconnect at any time with new keys.

Plan requirement

The Voice Assistant (Vapi integration) is available on Pro and Ultimate plans.

Installing the widget

Navigate to Integrations in the sidebar. You'll see your Organization ID and integration options for different platforms.

Supported platforms

• HTML — add a script tag to any static website.
• React — embed in any React application.
• Next.js — integrate with your Next.js project.
• JavaScript — add to any JavaScript-based application.

All platforms use the same embed code — a single <script> tag with your Organization ID:

Installation steps

1. Copy your Organization ID from the Integrations page.
2. Click any platform card (HTML, React, Next.js, or JavaScript) to open the integration dialog.
3. Copy the embed code snippet.
4. Paste it inside the <head> or before </body> of your page.
5. The widget will appear as a floating button in the bottom-right corner of your site.

Widget position

By default, the floating button appears in the bottom-right corner. You can change this to bottom-left by adding data-position="bottom-left" to the script tag.

Widget behavior

The widget loads as a lightweight script that creates a 60×60px floating button. When clicked, it opens a 400×600px iframe with rounded corners and a shadow. The iframe has permissions for microphone (voice calls), clipboard read, and clipboard write.

Available plans

Cassandra AI offers three subscription tiers, each unlocking progressively more features. Plans are managed through Clerk's billing system with Stripe for secure payments.

Feature comparison

How to subscribe

1. Go to Plans & Billing in the sidebar.
2. Review the available plans and select the one that fits your needs.
3. Complete the checkout through Stripe's secure payment page.
4. After successful payment, your plan is activated instantly and you're redirected to /conversations.

Feature overlays

If you try to access a feature that requires a higher plan, you'll see a friendly overlay explaining what's included and a button to view plans or upgrade. There are two types:

• Premium Feature Overlay (requires Pro+): shown on Knowledge Base, Agent Settings, and Voice Assistant pages.
• Ultimate Feature Overlay (requires Ultimate): shown on AI Persona and Widget Customization pages.

Layout overview

The dashboard uses a sidebar-based layout with a collapsible navigation panel on the left, a navbar at the top with the sidebar trigger and theme toggle, and the main content area.

Sidebar navigation

The sidebar is organized into four groups:

• Customer Support: Conversations
• AI Agent: AI Persona (Ultimate), Knowledge Base (Pro), Agent Settings (Pro), Widget Customization (Ultimate)
• Configuration: Integrations (Free), Voice Assistant (Pro)
• Account: Plans & Billing (Free)

Menu items that require a higher plan show a subtle indicator. The sidebar also contains the Organization Switcher in the header and the User Button (profile/logout) in the footer.

Theme toggle

The animated day/night toggle in the navbar lets you switch between light and dark mode. Your preference is saved and applied across the entire platform, including Clerk's UI components (organization switcher, user button, pricing table).

Responsive design

On mobile devices, the sidebar collapses into a hamburger menu. The conversations page adapts by stacking panels vertically — tap a conversation to see its chat, and use the back button to return to the list.