> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Channels

> Team collaboration and real-time messaging for group and direct conversations

## Overview

Channels in Open WebUI provide a powerful team collaboration system with support for group messaging, direct messages, threaded conversations, and AI model mentions. Built on WebSocket technology, channels offer real-time synchronization across all connected devices.

## Channel Types

Open WebUI supports three distinct channel types:

<Tabs>
  <Tab title="Standard Channels">
    Public or private channels created by admins for organization-wide communication:

    * **Access Control**: Managed through user and group permissions
    * **Visibility**: Can be public (all users) or restricted
    * **Use Case**: Announcements, team discussions, topic-based conversations
  </Tab>

  <Tab title="Group Channels">
    Private channels for team collaboration:

    * **Membership-Based**: Only invited members can access
    * **Created by Users**: Any user can create group channels
    * **Active Status**: Track which members are currently engaged
  </Tab>

  <Tab title="Direct Messages (DM)">
    One-on-one or small group private conversations:

    * **Automatic Creation**: Created when messaging a user
    * **User Status**: Shows active/inactive status of participants
    * **Privacy**: Only participants have access
  </Tab>
</Tabs>

<Note>
  Channel functionality must be enabled through `ENABLE_CHANNELS` configuration and requires the `features.channels` permission for non-admin users.
</Note>

## Creating Channels

### Direct Messages

Start a conversation with any user:

<Steps>
  <Step title="Select User">
    Navigate to the user you want to message, or use the API with their user ID
  </Step>

  <Step title="Auto-Create DM Channel">
    ```bash theme={null}
    # API endpoint: GET /api/v1/channels/users/{user_id}
    curl -X GET "https://your-instance/api/v1/channels/users/user-123" \
      -H "Authorization: Bearer YOUR_TOKEN"
    ```

    Returns existing DM or creates a new one automatically
  </Step>

  <Step title="Start Messaging">
    The channel is immediately active with real-time WebSocket connection
  </Step>
</Steps>

### Group Channels

Create private team channels:

```python theme={null}
# API endpoint: POST /api/v1/channels/create
{
  "type": "group",
  "name": "Engineering Team",
  "description": "Discussion channel for engineering",
  "is_private": true,
  "user_ids": ["user-1", "user-2", "user-3"],
  "group_ids": ["group-engineering"]
}
```

### Standard Channels (Admin Only)

Create organization-wide channels:

```python theme={null}
# API endpoint: POST /api/v1/channels/create
# Requires admin role
{
  "type": null,  # or "" for standard channel
  "name": "general",
  "description": "Company-wide announcements",
  "access_grants": [
    {
      "principal_type": "user",
      "principal_id": "*",
      "permission": "read"
    }
  ]
}
```

<Warning>
  Only admins can create standard channels. Regular users are limited to group and DM channels.
</Warning>

## Channel Management

### Listing Channels

View all accessible channels:

<Tabs>
  <Tab title="User View">
    ```bash theme={null}
    GET /api/v1/channels/
    ```

    Returns channels with:

    * **Last Message Time**: When the last message was sent
    * **Unread Count**: Number of unread messages since last read
    * **User Status**: For DM channels, shows participant online status
    * **User IDs**: List of all members (group/DM only)
  </Tab>

  <Tab title="Admin View">
    ```bash theme={null}
    GET /api/v1/channels/list
    ```

    Returns all channels in the system for administrative management
  </Tab>
</Tabs>

### Updating Channels

Modify channel settings:

```python theme={null}
# API endpoint: POST /api/v1/channels/{id}/update
# Requires channel ownership or admin role
{
  "name": "Updated Channel Name",
  "description": "New description",
  "is_private": true,
  "access_grants": [
    {
      "principal_type": "group",
      "principal_id": "group-id",
      "permission": "write"
    }
  ]
}
```

### Member Management

<CardGroup cols={2}>
  <Card title="Add Members" icon="user-plus">
    ```python theme={null}
    # POST /api/v1/channels/{id}/update/members/add
    {
      "user_ids": ["user-1", "user-2"],
      "group_ids": ["group-engineering"]
    }
    ```

    Automatically invites all users in specified groups
  </Card>

  <Card title="Remove Members" icon="user-minus">
    ```python theme={null}
    # POST /api/v1/channels/{id}/update/members/remove
    {
      "user_ids": ["user-3"]
    }
    ```

    Removes users from channel membership
  </Card>

  <Card title="View Members" icon="users">
    ```bash theme={null}
    GET /api/v1/channels/{id}/members?page=1
    ```

    Paginated member list (30 per page) with search and filtering
  </Card>

  <Card title="Update Active Status" icon="toggle-on">
    ```python theme={null}
    # POST /api/v1/channels/{id}/members/active
    {"is_active": true}
    ```

    Mark channel as active/archived in your channel list
  </Card>
</CardGroup>

## Messaging

### Sending Messages

Post messages to channels:

```python theme={null}
# API endpoint: POST /api/v1/channels/{id}/messages/post
{
  "content": "Hello @user-name! Check out @model-gpt-4",
  "parent_id": null,  # null for main messages, message_id for replies
  "temp_id": "temp-123",  # Client-generated ID for optimistic updates
  "data": {
    "files": [
      {"id": "file-123", "type": "image", "url": "..."}
    ]
  },
  "meta": {}
}
```

<Tip>
  Messages support @mentions for users and AI models. Mentioning a model triggers an automatic AI response in the thread.
</Tip>

### Message Features

<Tabs>
  <Tab title="Threading">
    Create organized discussions:

    * **Parent Messages**: Top-level messages in the channel
    * **Thread Replies**: Set `parent_id` to reply to a message
    * **Reply Count**: Automatically tracked for each parent message
    * **Latest Reply Time**: Shows when threads were last active
  </Tab>

  <Tab title="Reactions">
    Express feedback quickly:

    * Add emoji reactions to any message
    * View all reactions per message
    * Multiple reactions per user supported
  </Tab>

  <Tab title="Pinned Messages">
    Highlight important messages:

    ```python theme={null}
    # POST /api/v1/channels/{id}/messages/{message_id}/pin
    {"is_pinned": true}
    ```

    Retrieve pinned messages:

    ```bash theme={null}
    GET /api/v1/channels/{id}/messages/pinned?page=1
    ```
  </Tab>

  <Tab title="File Attachments">
    Share files in messages:

    * Images render inline
    * Files tracked in `channel_file` table
    * Automatic cleanup on message deletion
  </Tab>
</Tabs>

### AI Model Integration

Mention AI models to get responses:

<Steps>
  <Step title="Mention a Model">
    Use `@model-name` syntax in your message:

    ```
    Hey @gpt-4, can you explain this code?
    ```
  </Step>

  <Step title="Automatic Response">
    The mentioned model automatically:

    * Creates a reply in the thread
    * Includes full thread history for context
    * Supports image attachments in the conversation
  </Step>

  <Step title="Model Context">
    Models receive:

    * Thread history with usernames
    * Previous model responses
    * Image attachments from the conversation
    * Custom system prompt based on thread context
  </Step>
</Steps>

<Note>
  Replying to a model's message automatically mentions that model again, creating a continuous conversation.
</Note>

### Retrieving Messages

Access channel messages:

```python theme={null}
# API endpoint: GET /api/v1/channels/{id}/messages?skip=0&limit=50
# Returns messages with:
{
  "id": "message-id",
  "content": "Message text",
  "user": {"id": "user-id", "name": "User Name"},
  "created_at": 1234567890,
  "reply_count": 5,
  "latest_reply_at": 1234567900,
  "reactions": [{"emoji": "👍", "user_id": "..."}],
  "data": {}  # Converted to boolean for efficiency
}
```

### Thread Conversations

View threaded replies:

```bash theme={null}
# API endpoint: GET /api/v1/channels/{id}/messages/{message_id}/thread
GET /api/v1/channels/{id}/messages/{message_id}/thread?skip=0&limit=50
```

## Real-Time Features

### WebSocket Events

Channels use WebSocket rooms for real-time updates:

<CardGroup cols={2}>
  <Card title="Channel Events" icon="broadcast-tower">
    Clients join room: `channel:{channel_id}`

    Events emitted:

    * `channel:created` - New channel available
    * `message` - New message posted
    * `message:update` - Message edited
    * `message:reply` - New thread reply
  </Card>

  <Card title="Active User Tracking" icon="eye">
    Track who's currently viewing the channel:

    ```python theme={null}
    active_users = get_user_ids_from_room(f"channel:{id}")
    ```

    Used for:

    * Read receipts
    * Typing indicators
    * Notification decisions
  </Card>
</CardGroup>

### Notifications

Automatic notifications for inactive users:

* **Webhook Support**: Send to user's configured webhook URL
* **Smart Delivery**: Only notifies users not actively viewing the channel
* **Rich Content**: Includes channel name, message content, and deep link
* **Custom Format**: Supports various notification platforms

```json theme={null}
// Notification payload
{
  "action": "channel",
  "message": "Message content",
  "title": "#channel-name",
  "url": "https://your-instance/channels/{id}"
}
```

## Channel Webhooks

Create incoming webhooks for external integrations:

### Creating Webhooks

```python theme={null}
# API endpoint: POST /api/v1/channels/{id}/webhooks/create
{
  "name": "GitHub Bot",
  "profile_image_url": "https://github.com/logo.png"
}

# Response includes secure token
{
  "id": "webhook-id",
  "token": "secure-token-...",
  "channel_id": "channel-id",
  ...
}
```

### Using Webhooks

<Steps>
  <Step title="Get Webhook URL">
    ```bash theme={null}
    POST /api/webhooks/{webhook_id}/{token}
    ```
  </Step>

  <Step title="Send Messages">
    ```python theme={null}
    curl -X POST "https://your-instance/api/webhooks/{id}/{token}" \
      -H "Content-Type: application/json" \
      -d '{
        "content": "Deployment successful!",
        "data": {"files": [...]}
      }'
    ```
  </Step>

  <Step title="Track Usage">
    `last_used_at` timestamp automatically updated on each webhook call
  </Step>
</Steps>

### Managing Webhooks

<CardGroup cols={2}>
  <Card title="List Webhooks" icon="list">
    ```bash theme={null}
    GET /api/v1/channels/{id}/webhooks
    ```
  </Card>

  <Card title="Update Webhook" icon="pen">
    ```python theme={null}
    POST /api/v1/channels/{id}/webhooks/{webhook_id}/update
    {"name": "New Name"}
    ```
  </Card>

  <Card title="Delete Webhook" icon="trash">
    ```bash theme={null}
    DELETE /api/v1/channels/{id}/webhooks/{webhook_id}/delete
    ```
  </Card>

  <Card title="Regenerate Token" icon="rotate">
    Delete and recreate the webhook to generate a new secure token
  </Card>
</CardGroup>

## Access Control

### Permission Levels

<Tabs>
  <Tab title="Read Access">
    Users can:

    * View channel and messages
    * Join the channel (standard channels only)
    * Read all message history
    * See member list
  </Tab>

  <Tab title="Write Access">
    Users can (in addition to read):

    * Post messages
    * Create threads
    * Add reactions
    * Pin messages (if member)

    Special rule: Users with public read access automatically get write permissions
  </Tab>

  <Tab title="Manager">
    Channel owners can:

    * Update channel settings
    * Manage members
    * Delete the channel
    * Create webhooks
  </Tab>
</Tabs>

### Access Grant Types

Configure channel access:

```python theme={null}
"access_grants": [
  {
    "principal_type": "user",
    "principal_id": "user-123",  # specific user
    "permission": "write"
  },
  {
    "principal_type": "group",
    "principal_id": "group-engineering",
    "permission": "read"
  },
  {
    "principal_type": "user",
    "principal_id": "*",  # all users (public)
    "permission": "read"
  }
]
```

<Warning>
  Group and DM channels ignore access grants and rely solely on membership. Only standard channels use the access grant system.
</Warning>

## Unread Tracking

Automatic read receipt system:

### How It Works

1. **Last Read Timestamp**: Each member has `last_read_at` timestamp
2. **Unread Count**: Calculated as messages created after `last_read_at`
3. **Auto-Update**: Joining a channel updates your `last_read_at`
4. **Manual Update**: Can explicitly mark as read via API

### Update Read Status

```python theme={null}
# API endpoint: POST /api/v1/channels/{id}/read
# Automatically updates last_read_at to current time
```

## Best Practices

### Channel Organization

<Tip>
  Use channel types effectively:

  * **Standard Channels**: Company announcements, general discussion
  * **Group Channels**: Project teams, department discussions
  * **DM Channels**: Quick questions, one-on-one conversations
</Tip>

### Message Threading

* **Keep Threads Focused**: Use threads for specific sub-topics
* **Reply in Threads**: Avoid cluttering main channel with extended discussions
* **Pin Important Messages**: Highlight key information for easy access

### AI Model Usage

* **Mention Specifically**: Use full model names for clarity
* **Provide Context**: Models see full thread history
* **Use Threads**: Keep AI conversations organized in threads

### Performance

* **Pagination**: Messages load 50 at a time by default
* **Active Members**: Track 30 members per page
* **Optimize Queries**: Use filters to reduce data transfer

## API Reference

<CardGroup cols={2}>
  <Card title="List Channels" icon="list">
    ```
    GET /api/v1/channels/
    ```

    User's accessible channels with unread counts
  </Card>

  <Card title="Get Channel" icon="eye">
    ```
    GET /api/v1/channels/{id}
    ```

    Full channel details with member info
  </Card>

  <Card title="Create Channel" icon="plus">
    ```
    POST /api/v1/channels/create
    ```

    Create group, DM, or standard channel
  </Card>

  <Card title="Update Channel" icon="pen">
    ```
    POST /api/v1/channels/{id}/update
    ```

    Modify channel settings (owner only)
  </Card>

  <Card title="Delete Channel" icon="trash">
    ```
    DELETE /api/v1/channels/{id}/delete
    ```

    Permanently remove channel
  </Card>

  <Card title="Post Message" icon="message">
    ```
    POST /api/v1/channels/{id}/messages/post
    ```

    Send message with optional threading
  </Card>
</CardGroup>

<Note>
  All API endpoints require authentication and respect channel access controls. Admins can optionally bypass restrictions with `ENABLE_ADMIN_CHAT_ACCESS` enabled.
</Note>