# Multiplayer Chat

Enable group conversations where multiple users can chat with your AI in a shared session via shareable links.

---

Multiplayer Chat lets multiple users join a single conversation with your AI. Share a link, and anyone who joins sees the same messages in real-time -- perfect for team collaboration, study groups, live demos, and collaborative problem-solving.

## How It Works

1. A user clicks **Start Group Chat** in your app's chat interface
2. A shareable link is generated
3. Anyone with the link can join the session (up to 50 participants)
4. All participants see messages in real-time as they're sent
5. The AI responds to the entire group in a single shared thread

## Enabling Multiplayer

Multiplayer Chat is available on all plans. To enable it:

1. Open your app in the builder
2. Go to **Build** → **Behavior**
3. Toggle on **Multiplayer Chat** ("Allow group chat sessions via shareable links")

That's it. A **Start Group Chat** button will appear in your consumer chat interface.

## The Consumer Experience

### Creating a Session

When a user clicks **Start Group Chat**, they become the first participant with a generated display name and unique avatar color. A shareable link and short token are displayed in a modal with a copy button.

### Joining a Session

Recipients click the shared link or enter the token manually. They immediately:
- Join the conversation as a new participant
- See the full message history up to that point
- Get a unique display name and avatar color
- Appear in the participant panel for everyone to see

### During the Conversation

| Feature | How It Works |
|---------|--------------|
| **Real-time messages** | Everyone sees messages instantly as they're sent |
| **Typing indicators** | Shows who's currently typing |
| **Participant panel** | View all active participants with names and colors |
| **AI responses** | Stream live for all participants simultaneously |
| **Join/leave notifications** | Participants are notified when someone joins or leaves |

### Identity Options

- **Anonymous:** Users can join without signing in (auto-generated names like "Quick Panda")
- **Authenticated:** Logged-in users appear with their profile name or email
- Both types participate equally in the conversation

### Leaving and Rejoining

- Click **Leave Group** to exit
- Rejoin anytime using the same link
- If connection drops, the participant has an 8-second grace period to reconnect before being marked as "left"

## How the AI Handles Groups

The AI operates at the **session level**, not per-user:

- One AI instance responds to the entire group
- Messages from all participants go into a single conversation thread
- The AI sees who said what and can reference previous context
- Responses are generated once and delivered to all participants simultaneously
- While the AI is responding, the input field is disabled for everyone to prevent conflicting messages

There are no private or "whisper" messages in multiplayer mode.

## Use Cases

| Scenario | Example |
|----------|---------|
| **Team brainstorming** | Product team collaborates with AI on feature ideas |
| **Study groups** | Students work through problems together with AI tutoring |
| **Live demos** | Show prospects your AI with multiple people in the room |
| **Customer meetings** | Client and support team interact with AI together |
| **Training sessions** | Instructor and trainees learn with AI assistance |

## Limits

- Maximum **50 participants** per session
- Sessions use standard token billing (one AI response per message, regardless of participant count)
- No additional cost for multiplayer -- it's included with your plan

## Troubleshooting

**"Start Group Chat" button not visible?**
- Verify Multiplayer Chat is enabled in Build → Behavior settings
- The button only appears in the consumer chat interface, not the builder preview

**Participants can't join?**
- Check that the share link is copied correctly
- Verify the session hasn't been closed by the creator
- Sessions support up to 50 participants

**Messages not appearing in real-time?**
- Check internet connection stability
- Participants with poor connections may experience brief delays
- The grace period system handles temporary disconnections automatically