Overview

Last Edit: Jun 06 2020

Almost all API requests are specific to a channel (e.g. add a message to channel “livestream:rockets”) and as we saw already, channels are organized in groups called channel types. All applications starts with five default channel types, each have different name and are preconfigured to best fit one use-case.

Channel types can be configured with specific permissions and features.

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

There are five built-in channel types:

  • Livestream: Sensible defaults in case you want to build chat like YouTube or Twitch.
  • Messaging: Configured for apps such as WhatsApp or Facebook Messenger.
  • Team: If you want to build your own version of Slack or something similar, start here.
  • Commerce: Good defaults for building something like your own version of Intercom or Drift.

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.
  • search: Controls if messages should be searchable (this is a premium feature).
  • reactions: If users are allowed to add reactions to messages.
  • replies: Enables message threads and 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.

Channel Types Fields

Name Type Description Default Optional
name string The name of the channel type must be unique per application
message_retention string A number of days or infinite infinite
max_message_length int The max message length 5,000
typing_events default Enable typing events default
read_events boolean Enable read events true
connect_events boolean Enable connect events true
search boolean Enable message search true
reactions boolean Enable message reactions true
replies boolean Enable replies (threads) true
mutes boolean Enable mutes true
uploads boolean Enable file and image upload true
url_enrichment boolean Automatically enrich URLs true
automod string Disabled, simple or AI are valid options for the Automod (AI based moderation is a premium feature) simple
commands list of string The commands that are available on this channel type []
You need to use server-side authentication to create, edit, or delete a channel type.

Creating a Channel Type


import { DenyAll, AnyRole } from 'stream-chat';

await client.createChannelType({
	name: 'public',
	mutes: false,
	reactions: false,
});
                    

client.create_channel_type(
    {
        "name": "public",
        "permissions": [
            dict(
                name="Allow reads for all",
                priority=999,
                resources=["ReadChannel", "CreateMessage"],
                action="Allow",
            ),
            dict(name="Deny all", priority=1, resources=["*"], action="Deny"),
        ],
        "mutes": False,
        "reactions": False,
    }
)
                    

client.create_channel_type({
    'name' => 'public',
    'permissions' => [
	{
	    'name' => 'Allow reads for all',
            'priority' => 999,
	    'resources' => ['ReadChannel', 'CreateMessage'],
	    'action' => 'Allow',
	},
	{'name' => 'Deny all', 'priority' => 1, 'resources' => ['*'], 'action' => 'Deny'}
    ],
    'mutes' => false,
    'reactions' => false
})$channelConf = [    'name' => 'public2',$channelConf = [    'name' => 'public2',    'permissions' => [		[		    'name' => 'Allow reads for all',    	          'priority' => 999,		    'resources' => ['ReadChannel', 'CreateMessage'],		    'action' => 'Allow',		],		[			'name' => 'Deny all', 			'priority' => 1,
                    

$channelConf = [
    'name' => 'public2',
    'permissions' => [
		[
		    'name' => 'Allow reads for all',
    	          'priority' => 999,
		    'resources' => ['ReadChannel', 'CreateMessage'],
		    'action' => 'Allow',
		],
		[
			'name' => 'Deny all', 
			'priority' => 1, 
			'resources' => ['*'], 
			'action' => 'Deny'
		]
    ],
    'mutes' => false,
    'reactions' => false
];

$type = $client->createChannelType($channelConf);
                    

// at the moment we don't have a Java client for server side usage
                    

// at the moment we don't have a Swift client for server side usage
                    

var c = new ChannelTypeInput()
{
    Name = "livechat",
    Automod = Autmod.Disabled,
    Commands = new List<string>() { Commands.Ban },
    Mutes = true
};

await client.CreateChannelType(c);
                    

newChannelType := &ChannelType{
	// Copy the default settings.
	ChannelConfig: DefaultChannelConfig,
}

newChannelType.Name = "public"
newChannelType.Mutes = false
newChannelType.Reactions = false
newChannelType.Permissions = append(newChannelType.Permissions,
	&Permission{
		Name:      "Allow reads for all",
		Priority:  999,
		Resources: []string{"ReadChannel", "CreateMessage"},
		Action:    "Allow",
	},
	&Permission{
		Name:      "Deny all",
		Priority:  1,
		Resources: []string{"*"},
		Action:    "Deny",
	},
)

client.CreateChannelType(newChannelType
                    
If not provided, the permission settings will default to the ones from the built-in "messaging" type.

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.


const channelTypes = await client.listChannelTypes();
                    

$types = $client->listChannelTypes();
                    

client.list_channel_types()
                    

client.ListChannelTypes()
                    

Get a Channel Type

You can retrieve a channel type definition with this endpoint. Note: features and commands are also returned by other channel endpoints.


const channelType = await client.getChannelType('public');
                    

$type = $client->getChannelType('public');
                    

client.get_channel_type("public")
                    

client.GetChannelType("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.


const update = await client.updateChannelType('public', {
    replies: false,
    commands: ["all"]
});
                    

$update = $client->updateChannelType('public', [
    'permissions' => [
		[
		    'name' => 'Allow reads for all - updated',
    	          'priority' => 999,
		    'resources' => ['*'],
		    'action' => 'Allow',
		],
		[
			'name' => 'Deny all - updated', 
			'priority' => 1, 
			'resources' => ['*'], 
			'action' => 'Deny'
		]
    ],
    'replies' => false,
    'commands' => ['all']
]);
                    

client.update_channel_type(
    "public",
    permissions=[
        dict(
            name="Allow reads for all",
            priority=999,
            resources=["ReadChannel", "CreateMessage"],
            role="*",
            action="Allow",
        ),
        dict(
            name="Deny all",
            priority=1,
            resources=["*"],
            role="*",
            action="Deny",
        ),
    ],
    replies=False,
    commands=["all"],
)
                    

client.UpdateChannelType("public", map[string]interface{}{
	"permissions": []map[string]interface{}{
		map[string]interface{}{
			"name":      "Allow reads for all",
			"priority":  999,
			"resources": []string{"ReadChannel", "CreateMessage"},
			"role":      "*",
			"action":    "Allow",
		},
		map[string]interface{}{
			"name":      "Deny all",
			"priority":  1,
			"resources": []string{"*"},
			"role":      "*",
			"action":    "Deny",
		},
	},
	"replies":  false,
	"commands": []string{"all"},
})
                    

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


const update = await client.updateChannelType("public", {
    typing_events: false,
    read_events: true,
    connect_events: true,
    search: false,
    reactions: true,
    replies: false,
    mutes: true
});
                    

$update = $client->updateChannelType('public', [
    'typing_events' => false,
    'read_events' => true,
    'connect_events' => true,
    'search' => false,
    'reactions' => true,
    'replies' => false,
    'mutes' => true,
    'replies' => false
]);
                    

client.update_channel_type("public", 
    typing_events=False,
    read_events=True,
    connect_events=True,
    search=False,
    reactions=True,
    replies=False,
    mutes=True
)
                    

client.UpdateChannelType("public", map[string]interface{}{
	"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:


const update = await client.updateChannelType("public", {
    automod: "disabled",
    message_retention: "7",
    max_message_length: 140,
    commands: ["giphy", "ban"]
});
                    

$update = $client->updateChannelType('public', [
    'automod' => 'disabled',
    'message_retention' => '7',
    'max_message_length' => 140,
    'commands' => [ 'giphy', 'ban']
]);
                    

client.update_channel_type(
    "public",
    automod="disabled",
    message_retention="7",
    max_message_length=140,
    commands=["ban", "unban"],
)
                    

client.UpdateChannelType(
	"public",
	map[string]interface{}{
		"automod":            "disabled",
		"message_retention":  "7",
		"max_message_length": 140,
		"commands":           []interface{}{"ban", "unban"},
	},
)
                    

Remove a Channel Type


const destroy = await client.deleteChannelType('public');
                    

$client->deleteChannelType('public');
                    

client.delete_channel_type("public");
                    

client.DeleteChannelType("public")
                    
You cannot delete a channel type if there are any active channels of that type.