## Overview

**DEPRECATED**: Please use the "Citizen AI Streaming Chat" widget for new use cases. This widget is deprecated and will be removed in future versions.

The Chat Widget embeds an AI-powered chat interface on cplace pages where users can have conversational interactions with an AI assistant. It provides a low-code approach to building custom AI assistants by allowing developers to write CplaceJS scripts that define the chat behavior while leveraging the platform's AI infrastructure for model connections, memory persistence, and tool execution.

## Use Cases

### Custom AI Chat Assistants
Create page-specific AI assistants that can answer questions about projects, summarize data, or provide contextual help based on the page content.

### Data-Driven Conversations
Build chat interfaces that can query and reason about pages retrieved from searches or connected tables, enabling users to ask questions about collections of data.

### Guided User Interactions
Use prompt suggestions to guide users toward common questions or actions, making the AI more discoverable and useful for specific workflows.

### User-Specific vs. Shared Conversations
Support both individual chat histories (each user sees their own conversation) or shared chat rooms (all users see the same conversation).

### AI-Assisted Page Operations
Allow the assistant to perform actions on pages (read/write) through No-Code Tools configured on the AI Assistant.

## Example Scenarios

- **Project Dashboard Chat**: A project manager views a project page and asks the AI to "summarize the open high risks" - the AI analyzes related risk pages and provides a summary
- **Document Q&A**: Users ask questions about documents embedded or linked to a page
- **Status Reports**: Users request "create a management summary" and the AI generates a report based on configured data sources
- **Interactive Help**: Domain-specific help that understands the context of the current page

## Design Considerations

### Script-Based Architecture
The widget requires a CplaceJS script with `checkAccess()` and `call()` functions. This provides flexibility but requires low-code development skills.

### Memory Persistence
Chat history is automatically persisted, with options for user-specific or shared conversation history. Configure `maxMessages` to control memory retention.

### Data Source Integration
The widget can access pages from multiple sources: search queries, explicit selection, or connected table widgets. This determines what context is available to the AI.

### Permission Model
- Only users with Low-Code permission can embed the widget
- Runtime access is controlled by the `checkAccess()` function in the script
- Widget can only be embedded in spaces where Citizen AI app is present

## Common Pitfalls

- Forgetting to implement the required `checkAccess()` function in the script
- Not considering memory limits when dealing with long conversations
- Assuming the widget works without the Citizen AI plugin being active in the space

## Alternatives

| Widget | When to Use Instead |
|--------|---------------------|
| **Citizen AI Streaming Chat** | Recommended for all new use cases - this is the replacement for the deprecated Chat Widget |
| **Ask Your Page Widget** (`cf.cplace.citizenAi.askYourPageWidget`) | When you need simple, pre-configured "Ask Your Page" functionality without custom scripting |
| **Low-Code Widget Builder** (Embedded Widget `cf.cplace.lowCodeWidgetBuilder.embeddedWidget`) | When you need a full custom HTML/CSS/JS widget with your own UI and write-back rather than a chat interface — author it in the Widget Builder and embed it. AI calls can still be made from the widget's server script via Citizen AI. |

## Related Patterns

- **AI Assistant Configuration** - Assistants created via the script can be configured with system messages, tools, and model parameters
- **Connected Table Pattern** - Use `connectedTable` data source to let users ask questions about data displayed in another widget