ds_zagres_ai/TEAM_CHAT_GUIDE.md

# Team Chat Guide

This guide explains how to use the team chat feature with OpenWebUI channels.

## Overview

The chatbot now integrates with OpenWebUI's channels feature to provide team chat functionality. When you create a team chat in the chatbot, it automatically creates a corresponding channel in OpenWebUI, allowing multiple users to participate in the same conversation.

## Using Team Chats

### AI Responses in Team Chats

When you send a message in a team chat, the AI will respond both in your local chat and in the OpenWebUI channel. The AI's responses in OpenWebUI channels:

- Are prefixed with a robot emoji (🤖) to clearly identify them as AI responses
- Appear with a special "ai-assistant" user ID to distinguish them from human users
- Are visible to all members of the channel in real-time

This allows all team members to see the conversation with the AI and collaborate effectively.

### How the AI Bot is Triggered

The AI bot can be triggered to respond in two ways:

1. **Through the API**: When you send a message using the `/chats/{chat_id}/messages` endpoint, the AI automatically processes it and responds.

2. **Directly in OpenWebUI**: When someone mentions the AI in an OpenWebUI channel that's linked to a team chat:
   - The message is sent to your service through a webhook
   - If it contains an AI mention (like `@ai`, `@bot`, etc.), the AI processes it
   - The AI sends its response back to the OpenWebUI channel

By default, the AI only responds when explicitly mentioned with one of these triggers:
- `@ai`
- `@bot`
- `@assistant`
- `@chatbot`

You can customize these triggers or make the AI respond to all messages by changing the settings in your `.env` file:

```
# To customize the triggers that activate the AI
AI_TRIGGERS=@ai,@bot,@assistant,@chatbot

# To make the AI respond to all messages (not just mentions)
AI_RESPOND_TO_ALL=false  # Change to 'true' to respond to everything
```

This mention-based approach ensures the AI only joins the conversation when explicitly invited, making team chats more focused and preventing the AI from responding to every message.

### Creating a Team Chat

You can create a team chat in two ways:

1. **Through the API**:
   ```
   POST /chats
   {
     "user_id": "your-user-id",
     "title": "Team Chat Name",
     "model_id": "llama3.1",
     "is_team_chat": true
   }
   ```

2. **Through OpenWebUI**:
   - Log in to OpenWebUI at http://104.225.217.215:8080/
   - Navigate to the Channels section (look for a "#" or group icon in the sidebar)
   - Click "Create Channel" or "+" button
   - Give your channel a name and description
   - Choose whether it should be private or public
   - Click "Create"

### Adding Members to a Team Chat

1. **Through the API**:
   ```
   POST /chats/{chat_id}/members/{user_id}
   ```

2. **Through OpenWebUI**:
   - Open the channel in OpenWebUI
   - Look for a "Members" or "Invite" option
   - Add users by their username or email

### Sending Messages in a Team Chat

1. **Through the API**:
   ```
   POST /chats/{chat_id}/messages
   {
     "message": "Your message",
     "user_id": "your-user-id"
   }
   ```

2. **Through OpenWebUI**:
   - Open the channel in OpenWebUI
   - Type your message in the input box
   - Press Enter to send

### Viewing Team Chats

1. **Through the API**:
   ```
   GET /chats/user/{user_id}
   ```
   This will return all chats for the user, including team chats where they are a member.

2. **Through OpenWebUI**:
   - Log in to OpenWebUI
   - Navigate to the Channels section
   - You'll see all channels you're a member of

## Technical Implementation

The team chat feature works by:

1. Creating an OpenWebUI channel when a team chat is created
2. Adding members to both the local team chat and the OpenWebUI channel
3. Sending messages to both the local chat and the OpenWebUI channel
4. Deleting the OpenWebUI channel when the team chat is deleted

## Troubleshooting

If you encounter issues with team chats:

1. **Channel not appearing in OpenWebUI**:
   - Check if the OpenWebUI server is running
   - Verify that the OpenWebUI URL and API key are correctly configured in the `.env` file

2. **Cannot add members to a team chat**:
   - Ensure the user exists in OpenWebUI
   - Check if the team chat was properly created with `is_team_chat: true`

3. **Messages not appearing in OpenWebUI channel**:
   - Check the logs for any errors when sending messages
   - Verify that the OpenWebUI channel ID is correctly stored in the chat data

## API Reference

### Team Chat Endpoints

- `POST /chats` - Create a new chat (set `is_team_chat: true` for team chats)
- `GET /chats/user/{user_id}` - Get all chats for a user (includes team chats)
- `POST /chats/{chat_id}/members/{user_id}` - Add a user to a team chat
- `DELETE /chats/{chat_id}/members/{user_id}` - Remove a user from a team chat
- `DELETE /chats/{chat_id}` - Delete a chat (also deletes the OpenWebUI channel)

### OpenWebUI Channel Endpoints

- `GET /channels` - Get all OpenWebUI channels
- `GET /channels/{channel_id}` - Get an OpenWebUI channel by ID
- `POST /channels` - Create a new OpenWebUI channel