Add a chat widget or chat page
By the end of this page you will know how to embed one of your project’s AI Agents into your generated app as a chat, and which of the two chat types fits your use case.
When would you use this?
Once your app is generated, you may want part of it to hold a conversation. A chat surface embeds an existing AI Agent into the app without you hand-coding a chat UI. There are two shapes:
- “I want a help or support assistant available anywhere in my app.” Use Floating Chat: a small chat bubble that follows people around the app, or just the pages you choose. Good for general Q&A, customer support, or an always-available helper.
- “I want a focused, dedicated space for deeper conversations.” Use Chat Page: its own route and navigation entry, with a full-screen chat. Good when the conversation is the point of the page, such as an internal “Ask Data” analyst page or an onboarding assistant.
This is different from a Copilot app, which is its own standalone app type with a dedicated creation flow. A chat surface embeds an agent inside a Web app you’re already building. To run an agent from a button, or from your app’s server, see Agent integrations overview.
Prerequisites
- An app workspace with an active chat session (The generation flow).
- At least one active AI Agent in the project (Which agents you can use).
The chat types
| Type | What it adds | Agent types allowed |
|---|---|---|
| Floating Chat | A chat widget overlay on some or all pages | AI Agent |
| Chat Page | A dedicated route with a full chat UI | AI Agent |
Steps
Open the integration dialog
In the chat panel, click the + button (More options), then Add agent integration. If the app already has integrations, click + Add integration below the list. See Open the integration dialog.
Choose a chat type
Under Integration Type, pick Floating Chat (widget overlay) or Chat Page (dedicated route), in the Chat surfaces · AI agents only group.
Select an agent
Search and pick one of your project’s active AI Agents under Select Agent.
Configure the chat
The fields shown depend on the type you picked. Each example below uses an e-commerce admin app.
Floating Chat
| Field | What it controls | Example |
|---|---|---|
| Pages | all, or a comma-separated list of routes the widget appears on | /dashboard, /orders |
| Position | Bottom Right or Bottom Left | Bottom Right |
| Suggested Prompts | One per line — starter prompts shown in the widget | What's my best-selling product this week?Which orders need attention today?Summarize today's sales |
With these values, a chat bubble appears only on the Dashboard and Orders pages, bottom-right, with those three prompts ready to tap — a lightweight helper that doesn’t clutter every screen.
Chat Page
| Field | What it controls | Example |
|---|---|---|
| Route | The URL path for the new page. It must start with /. | /assistant |
| Page Title | The page’s display name | Store Assistant |
| Add to Navigation | Whether it gets a sidebar or navigation link (on by default) | On |
This adds a full Store Assistant page at /assistant, linked from the app’s navigation — a dedicated space for longer conversations.
Add the integration
Click Add Integration. qRaptor turns your configuration into a request in the chat panel and builds it like any other change, through the same generation flow as a normal follow-up.
Common issues
- No agents show up in the picker. Only active AI Agents are listed for Floating Chat and Chat Page. Task Agents can’t hold a conversation; use them with an Agent Action instead.
- Add Integration stays disabled. The message beside the button says what’s missing, such as Route is required or Route must start with ”/”.