# Chats

Chats are the heart of Gravity Rail. Every conversation between your AI and a person lives here — whether it started from a phone call, text message, web chat, email, Discord mention, or Slack DM. This is where you monitor what's happening, jump in when needed, and review how your AI is performing.

## Starting a Chat[​](#starting-a-chat "Direct link to Starting a Chat")

Most chats start automatically when someone reaches your workspace through a channel. But you can also start one manually:

1. Go to **Chats**
2. Click the **New Chat** icon (top right)
3. Pick a workflow; its active revision supplies the versioned assistant name and models
4. Optionally override the assistant name or models for this one chat
5. Start the conversation

Manual chats are useful for testing workflows or reaching out to specific members.

## Channels[​](#channels "Direct link to Channels")

Conversations can happen across multiple channels, and every channel feeds into the same chat interface:

| Channel         | How It Starts                                      |
| --------------- | -------------------------------------------------- |
| **Web Chat**    | Visitor opens the chat widget on one of your sites |
| **Web Voice**   | Visitor clicks the microphone icon on a site       |
| **Phone Voice** | Someone calls one of your phone numbers            |
| **Phone SMS**   | Someone texts one of your phone numbers            |
| **Email**       | Someone sends an email to one of your inboxes      |
| **Discord**     | Someone uses a slash command or @mentions your bot |
| **Slack**       | Someone @mentions your bot or sends a DM           |

The channel appears as an icon in the chat list so you can see at a glance how each conversation started.

## Chat States[​](#chat-states "Direct link to Chat States")

Every chat has a state that controls how it behaves:

| State        | What It Means                             | When to Use                                                 |
| ------------ | ----------------------------------------- | ----------------------------------------------------------- |
| **Active**   | AI responds automatically to new messages | Default state — the AI is handling it                       |
| **Paused**   | AI stands by — human takes over           | When you need to respond personally                         |
| **Muted**    | No notifications sent                     | For spam, abuse, or conversations you don't need alerts for |
| **Archived** | Conversation is complete                  | When the workflow is done                                   |

Toggle states from the chat header or the chat list.

## How Workflows Guide Chats[​](#how-workflows-guide-chats "Direct link to How Workflows Guide Chats")

Every chat follows a workflow, and understanding this relationship is key:

1. When a chat starts, it enters the workflow's **starting task**
2. The task provides the AI with its **prompt** (instructions), **goal** (when to move on), and **abilities** (what tools it can use)
3. As the conversation progresses, the AI moves between tasks based on goals and sub-task connections
4. Different tasks can collect different forms and use different tools while the Chat keeps the assistant configuration pinned by its Workflow revision

The current task shows in the chat header, so you always know where in the workflow a conversation is.

## What the AI Does During a Chat[​](#what-the-ai-does-during-a-chat "Direct link to What the AI Does During a Chat")

Your AI agent can:

* **Respond naturally** based on the task's prompt and the conversation history
* **Collect form data** by asking for information conversationally — it doesn't go field-by-field; it adapts to the flow
* **Switch tasks** when a goal is met or a user's needs change direction
* **Use abilities** like web search, calendar booking, file access, and custom tools
* **Escalate to humans** when it encounters something outside its scope

## Finding Chats[​](#finding-chats "Direct link to Finding Chats")

The chat list supports filtering to help you find what matters:

| Filter              | Shows                                                   |
| ------------------- | ------------------------------------------------------- |
| **Needs Response**  | Chats waiting for human attention (paused or escalated) |
| **Active / Paused** | Filter by AI response status                            |
| **Channel**         | Only show chats from a specific channel                 |
| **Assigned to Me**  | Conversations assigned to you                           |
| **Archived**        | Completed chats                                         |
| **Labels**          | Chats with specific labels                              |
| **Workflow**        | Chats in a specific workflow                            |

To save, name, and reuse filter combinations, see the **[Filters](https://docs.gravityrail.com/user-guide/filters.md)** guide.

### What the filter bar shows — and the one thing it can't[​](#what-the-filter-bar-shows--and-the-one-thing-it-cant "Direct link to What the filter bar shows — and the one thing it can't")

Everything narrowing the chat list is shown in the filter bar, and you can edit or remove any of it. When you open Chats without picking a view, the bar shows three conditions: not archived, chat type is Workflow Chat, and not a test chat. That is the whole filter — nothing else is applied behind the scenes.

There is one deliberate exception, and it is a permission, not a filter:

* **Chats from unknown callers** (people who reached you before they were matched to a member record — an unrecognised phone number, for example) are only visible to people with the **chat administrator** permission.
* If you have that permission, those chats appear in the normal views alongside everyone else's, because nothing is hiding them. You will see more rows than before. There is also an **Anonymous** view that shows only those chats.
* If you don't have it, those chats are never returned to you, and you won't see a chip in the filter bar offering to include them. Showing one would imply you could switch it off, and you can't — this is enforced on the server, on every view, saved filter, count, and export.

To go back to the old, narrower list, add an **Anonymous is false** condition to the filter bar yourself. It is a normal, removable condition.

If you clear every condition, the bar says **"No filters — showing all chats you can see."** That is exactly what it means: no narrowing at all, apart from the permission above. Archived and test chats come back in that state, because nothing is filtering them out any more.

## Quick Actions[​](#quick-actions "Direct link to Quick Actions")

From any chat, you can:

* **Pause / Resume** — Toggle whether the AI responds automatically
* **Mute** — Stop notifications for this chat
* **Archive** — Mark the conversation as complete
* **Assign** — Hand to a specific team member
* **View Member** — Jump to the person's profile and data
* **Generate Summary** — Create an AI-powered summary of the conversation (see below)
* **Rate assistant messages** — Thumbs up or down on an AI reply (optional short comment via **Add details**)

## Rating Assistant Messages[​](#rating-assistant-messages "Direct link to Rating Assistant Messages")

Use thumbs under an assistant message to mark quality:

1. Hover or focus the message and click **thumbs up** or **thumbs down**
2. Optionally click **Add details** to leave a short note about what was helpful or unhelpful
3. Your rating stays highlighted after you reload the page

Ratings are stored in your workspace (not only in external observability tools). When the chat belongs to a workflow, they also appear on that workflow’s **Feedback** tab so builders can review patterns across conversations. See **[Workflows — Reviewing Feedback](https://docs.gravityrail.com/user-guide/workflows.md#reviewing-feedback)**.

## Chat Summaries[​](#chat-summaries "Direct link to Chat Summaries")

Generate AI-powered summaries to quickly understand what happened in a conversation:

1. In the chat list, expand a row by clicking the chevron
2. Click **Generate Summary**
3. The system analyzes the conversation and produces a concise summary, auto-generated title, and optional label updates

Summaries are especially useful for long conversations, handoffs between team members, and post-conversation reporting.

## Exporting Chats[​](#exporting-chats "Direct link to Exporting Chats")

You can export chat data for compliance, records management, and offline review:

* **Single chat (JSONL)** — download a full transcript of one conversation including all messages, metadata, and tool calls
* **Bulk export (CSV)** — export all chats (or a filtered subset) as a spreadsheet

> **PHI notice:** Exported files may contain Protected Health Information. Handle them according to your organization's data policies.

See **[Exporting Chats](https://docs.gravityrail.com/user-guide/chats/export.md)** for step-by-step instructions, permission requirements, and file format details.

## Tips[​](#tips "Direct link to Tips")

* **Use "Needs Response" as your dashboard** — This filter shows you everything that requires human attention
* **Pause before replying** — When you want to take over from the AI, pause the chat first so it doesn't respond while you're typing
* **Archive completed conversations** — Keeping your active chat list clean makes it easier to spot what needs attention
* **Label chats for reporting** — Apply labels to categorize conversations by topic, outcome, or priority
* **Rate weak replies** — Thumbs-down on assistant messages (with a short comment) so builders can find them on the workflow **Feedback** tab

## Related[​](#related "Direct link to Related")

* **[Workflows](https://docs.gravityrail.com/user-guide/workflows.md)** — Building the conversation flows that guide chats
* **[Workflows — Reviewing Feedback](https://docs.gravityrail.com/user-guide/workflows.md#reviewing-feedback)** — Review thumbs and comments across a workflow
* **[Actions](https://docs.gravityrail.com/user-guide/automation/actions.md)** — Automating responses to chat events
* **[Channels](https://docs.gravityrail.com/user-guide/channels/.md)** — Setting up the channels that create chats
* **[Labels](https://docs.gravityrail.com/user-guide/knowledge/labels.md)** — Organizing chats with color-coded tags
* **[Filters](https://docs.gravityrail.com/user-guide/filters.md)** — Save reusable search rules for the chat list

## For developers[​](#for-developers "Direct link to For developers")

* **[Chats API](https://docs.gravityrail.com/developer/api/workspace/chats)** — list, read, and manage Chats and their messages programmatically
* **[Chat Labels API](https://docs.gravityrail.com/developer/api/workspace/chat_labels)** — apply and manage labels on Chats
* **[TypeScript SDK](https://docs.gravityrail.com/developer/guides/typescript-sdk)** — typed client for these endpoints