Channels - Open WebUI

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:

Standard Channels
Group Channels
Direct Messages (DM)

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

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

Creating Channels

Direct Messages

Start a conversation with any user:

Select User

Navigate to the user you want to message, or use the API with their user ID

Auto-Create DM Channel

# 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

Start Messaging

The channel is immediately active with real-time WebSocket connection

Group Channels

Create private team channels:

# 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:

# 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"
    }
  ]
}

Only admins can create standard channels. Regular users are limited to group and DM channels.

Channel Management

Listing Channels

View all accessible channels:

User View
Admin View

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)

GET /api/v1/channels/list

Returns all channels in the system for administrative management

Updating Channels

Modify channel settings:

# 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

Add Members

# 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

Remove Members

# POST /api/v1/channels/{id}/update/members/remove
{
  "user_ids": ["user-3"]
}

Removes users from channel membership

View Members

GET /api/v1/channels/{id}/members?page=1

Paginated member list (30 per page) with search and filtering

Update Active Status

# POST /api/v1/channels/{id}/members/active
{"is_active": true}

Mark channel as active/archived in your channel list

Messaging

Sending Messages

Post messages to channels:

# 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": {}
}

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

Message Features

Threading
Reactions
Pinned Messages
File Attachments

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

Highlight important messages:

# POST /api/v1/channels/{id}/messages/{message_id}/pin
{"is_pinned": true}

Retrieve pinned messages:

GET /api/v1/channels/{id}/messages/pinned?page=1

Share files in messages:

Images render inline
Files tracked in channel_file table
Automatic cleanup on message deletion

AI Model Integration

Mention AI models to get responses:

Mention a Model

Use @model-name syntax in your message:

Hey @gpt-4, can you explain this code?

Automatic Response

The mentioned model automatically:

Creates a reply in the thread
Includes full thread history for context
Supports image attachments in the conversation

Model Context

Models receive:

Thread history with usernames
Previous model responses
Image attachments from the conversation
Custom system prompt based on thread context

Replying to a model’s message automatically mentions that model again, creating a continuous conversation.

Retrieving Messages

Access channel messages:

# 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:

# 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:

Channel Events

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

Active User Tracking

Track who’s currently viewing the channel:

active_users = get_user_ids_from_room(f"channel:{id}")

Used for:

Read receipts
Typing indicators
Notification decisions

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

// 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

# 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

Get Webhook URL

POST /api/webhooks/{webhook_id}/{token}

Send Messages

curl -X POST "https://your-instance/api/webhooks/{id}/{token}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Deployment successful!",
    "data": {"files": [...]}
  }'

Track Usage

last_used_at timestamp automatically updated on each webhook call

Managing Webhooks

List Webhooks

GET /api/v1/channels/{id}/webhooks

Update Webhook

POST /api/v1/channels/{id}/webhooks/{webhook_id}/update
{"name": "New Name"}

Delete Webhook

DELETE /api/v1/channels/{id}/webhooks/{webhook_id}/delete

Regenerate Token

Delete and recreate the webhook to generate a new secure token

Access Control

Permission Levels

Read Access
Write Access
Manager

Users can:

View channel and messages
Join the channel (standard channels only)
Read all message history
See member list

Access Grant Types

Configure channel access:

"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"
  }
]

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

Unread Tracking

Automatic read receipt system:

How It Works

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

Update Read Status

# API endpoint: POST /api/v1/channels/{id}/read
# Automatically updates last_read_at to current time

Best Practices

Channel Organization

Use channel types effectively:

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

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

List Channels

GET /api/v1/channels/

User’s accessible channels with unread counts

Get Channel

GET /api/v1/channels/{id}

Full channel details with member info

Create Channel

POST /api/v1/channels/create

Create group, DM, or standard channel

Update Channel

POST /api/v1/channels/{id}/update

Modify channel settings (owner only)

Delete Channel

DELETE /api/v1/channels/{id}/delete

Permanently remove channel

Post Message

POST /api/v1/channels/{id}/messages/post

Send message with optional threading

All API endpoints require authentication and respect channel access controls. Admins can optionally bypass restrictions with ENABLE_ADMIN_CHAT_ACCESS enabled.

​Overview

​Channel Types

​Creating Channels

​Direct Messages

​Group Channels

​Standard Channels (Admin Only)

​Channel Management

​Listing Channels

​Updating Channels

​Member Management

Add Members

Remove Members

View Members

Update Active Status

​Messaging

​Sending Messages

​Message Features

​AI Model Integration

​Retrieving Messages

​Thread Conversations

​Real-Time Features

​WebSocket Events

Channel Events

Active User Tracking

​Notifications

​Channel Webhooks

​Creating Webhooks

​Using Webhooks

​Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Regenerate Token

​Access Control

​Permission Levels

​Access Grant Types

​Unread Tracking

​How It Works

​Update Read Status

​Best Practices

​Channel Organization

​Message Threading

​AI Model Usage

​Performance

​API Reference

List Channels

Get Channel

Create Channel

Update Channel

Delete Channel

Post Message

Overview

Channel Types

Creating Channels

Direct Messages

Group Channels

Standard Channels (Admin Only)

Channel Management

Listing Channels

Updating Channels

Member Management

Messaging

Sending Messages

Message Features

AI Model Integration

Retrieving Messages

Thread Conversations

Real-Time Features

WebSocket Events

Notifications

Channel Webhooks

Creating Webhooks

Using Webhooks

Managing Webhooks

Access Control

Permission Levels

Access Grant Types

Unread Tracking

How It Works

Update Read Status

Best Practices

Channel Organization

Message Threading

AI Model Usage

Performance

API Reference