Channel Types

Channel types allow you to configure which features are enabled, and how permissions work. For example you can disable typing indicators, give rights to moderators, or configure channels to be accessible even if you're not a member.

The easiest way to change your channel types is the dashboard. The docs below show how to change channel types via the API.

Built-in Channel types

There are six built-in channel types with good default for these use cases.

• Messaging: Good default for dating, marketplace, and other social app chat use cases
• Agent: For conversations between a user and an AI agent. See The agent channel type below.
• Livestream: For livestreaming or live shopping experiences
• Team: If you want to build your own version of Slack or something similar, start here.
• Gaming: Defaults for adding chat to video games.
• Commerce: For conversations between customers and businesses, such as marketplace and support chat.

The six default channel types come with good default permission policies. You can find more information on how to manage permissions in the Channel Types section.

The agent channel type

agent is built for conversations between a user and an AI agent. Like messaging, it is available on every app without any setup: create a channel of type agent, add the user and your agent's Stream user as members, and have your backend post the agent's answers in the channel. See AI Message Streaming for how to stream an LLM response into a message.

Its defaults follow from that use case. Answers can be long, the conversation history stays searchable, and a visitor can start a conversation as a guest user, before they sign up.

Features

Every setting not listed below has the same default as messaging.

The other defaults, shared with messaging: read events, read receipts, connect events, custom events, reactions, search, replies, quotes, mutes, uploads, URL enrichment and push notifications are enabled. User message reminders, polls, location sharing and message counting are disabled, and automod is off.

• Message limits. Message text can be up to 50,000 characters, counted as Unicode characters rather than bytes, and a message can carry up to 50 KB of custom data. Both limits are fixed for agent: setting max_message_length on the channel type or in a channel's config_overrides does not change them. The type always reports max_message_length: 50000, so client SDKs that check the length before sending allow the full 50,000 characters. Attachment limits are the same as on every other type.
• No typing events. typing.start and typing.stop are rejected on agent channels. To show that the agent is working on an answer, send the ai_indicator.update and ai_indicator.clear events described in AI Message Streaming.
• No slash commands. A message that starts with / (for example /giphy summarize this) is stored as plain text and no command runs, so users can send prompts that start with a slash.

Permissions

Membership is what grants access, as on messaging: a user can only read and write the agent channels they are a member of. The difference is guest access. Users and guests can create agent channels client-side, including channels with other users as members (such as your agent's user), and the user who created a channel keeps owner permissions on it even if they did not add themselves as a member.

Server-side requests are not restricted. The full list of grants for each role is in the Permissions Reference. On apps that still use the v1 permission policies, a creator who is not a member can read, update and delete the channel but not send messages, as on messaging.

Restricting guest access

To return guests to the messaging behavior, where a guest can only use channels they were added to as a member, remove all grants of the guest role on the agent channel type:

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.update_channel_type('agent', Models::UpdateChannelTypeRequest.new(
  grants: {
    'guest' => [] # guests can no longer create agent channels or act as owners
  }
))

Guests who are members of an agent channel keep reading and writing it, through the channel_member role.

To stop guests from creating channels but keep their owner access, read the type's current grants with getChannelType("agent"), remove create-channel from the guest list and send the rest back. A role's grants on a channel type are replaced as a whole list (the ! prefix only works in channel-level grants modifiers). To turn off guest users for the whole app, disable guest user creation in the Dashboard.

Guests in agent channels

Guest users keep the limits they have on every channel type: they are not available to multi-tenant apps, they do not get offline sync or unread counts, and they cannot upload files outside a channel. Uploads in an agent channel work for a guest who is a member or its creator. See Authless Users.

If your app already has an agent channel type

If you created a custom channel type named agent before it became built-in, its stored settings keep applying. Its permissions can change, though: a role with no grants stored on that type now falls back to the agent defaults above instead of the messaging ones, so guests can create channels and act as owners. Check its grants with getChannelType("agent") and store explicit grants for any role that should keep its previous behavior.

Updating or creating a channel type

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Create a new channel type
client.chat.create_channel_type(Models::CreateChannelTypeRequest.new(
  name: 'my-channel-type',
  typing_events: true,
  read_events: true,
  reactions: true,
  replies: true
))

# Update an existing channel type
client.chat.update_channel_type('my-channel-type', Models::UpdateChannelTypeRequest.new(
  reactions: false,
  max_message_length: 1000
))

Features you can enable/disable

Channel types can be configured with specific permissions and features.

As you can see in the examples below, you can define your own Channel types and configure them to fit your needs. The Channel type allows you to configure these features:

• typing_events : Controls if typing indicators are shown.
• read_events : Controls whether the chat shows how far you've read.
• connect_events : Determines if events are fired for connecting and disconnecting to a chat.
• custom_events : Determines if channel watchers will receive custom events.
• reactions : If users are allowed to add reactions to messages.
• search : Controls if messages should be searchable.
• replies : Enables message threads and replies.
• quotes : Allows members to quote messages (inline replies).
• mutes : Determines if users are able to mute other users.
• uploads : Allows image and file uploads within messages.
• url_enrichment : When enabled, messages containing URLs will be enriched automatically with image and text related to the message. This is disabled by default for the livestream channel type and we do not recommend enabling it for performance reasons.
• count_messages : Enables message counting on new channels. When enabled the message count will be present in the channel response.
• user_message_reminders : Allow users to set reminders for messages. More information can be found here.
• mark_messages_pending : When enabled, messages marked as pending are only visible to the sender until approved.
• polls : Allows channel members to create and vote on polls.
• skip_last_msg_update_for_system_msgs : When disabled, system messages will affect the channel's last_message_at timestamp.
• location_sharing : Allows members to share their locations with other members.
• read_receipts : Allows members to see when messages are delivered (delivery events).
• partitioning : Automatically chunks messages into virtual partitions for better performance at larger scales (dynamic partitioning).
• push_notifications : If messages are allowed to generate push notifications.

Channel Types Fields

Creating a Channel Type

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.create_channel_type(Models::CreateChannelTypeRequest.new(
  name: 'public',
  mutes: false,
  reactions: false
))

Please note that applications have a hard limit of 50 channel types. If you need more than this please have a look at the Multi-tenant & Teams section.

List Channel Types

You can retrieve the list of all channel types defined for your application.

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.list_channel_types

Get a Channel Type

You can retrieve a channel type definition with this endpoint.

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.get_channel_type('public')

Edit a Channel Type

Channel type features, commands and permissions can be changed. Only the fields that must change need to be provided, fields that are not provided to this API will remain unchanged.

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.update_channel_type('public', Models::UpdateChannelTypeRequest.new(
  replies: false,
  commands: ['all']
))

Features of a channel can be updated by passing the boolean flags:

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.update_channel_type('public', Models::UpdateChannelTypeRequest.new(
  typing_events: false,
  read_events: true,
  connect_events: true,
  search: false,
  reactions: true,
  replies: false,
  mutes: true
))

Settings can also be updated by passing in the desired new values:

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.update_channel_type('public', Models::UpdateChannelTypeRequest.new(
  automod: 'disabled',
  max_message_length: 140,
  commands: ['ban', 'unban']
))

Remove a Channel Type

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.delete_channel_type('public')