Overview

Last Edit: Mar 03 2020

Most API requests are specific to a channel (e.g. add a message to channel “livestream:rockets”). Channel types have different permissions and can be configured via APIs. 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.
  • Gaming: Configured for in-game chat.
  • 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. Enabled by default.
  • read_events: Controls whether the chat shows how far you’ve read. Enabled by default.
  • connect_events: Determines if events are fired for connecting and disconnecting to a chat. Enabled by default.
  • search: Controls if messages should be searchable (this is a premium feature). Disabled by default.
  • reactions: If users are allowed to add reactions to messages. Enabled by default.
  • replies: Enables message threads and replies. Enabled by default.
  • mutes: Determines if users are able to mute other users. Enabled by default.
  • uploads: Allows image and file uploads within messages. Enabled by default.
  • url_enrichment: When enabled, messages containing URLs will be enriched automatically with image and text related to the message. Enabled by default.

It allows you to specify these settings:

Name Type Description Default Optional
automod string Disabled, simple or AI are valid options for the Automod (AI based moderation is a premium feature) simple
message_retention string A number of days or infinite infinite
max_message_length int The max message length 5,000
default default default default
You need to use server-side authentication to create, edit, or delete a channel type.

Creating a Channel Type


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

await client.createChannelType({
    name: 'public', 
    permissions:[
        new Permission(
            name: 'Allow reads for all',
            priority: 999,
            resources: ['ReadChannel', 'CreateMessage'],
            AnyRole,
        ),
        DenyAll
    ],
    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 policies will default to the ones from the built-in team type.

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', {
    permissions: [AllowAll, DenyAll],
    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"},
	},
)
                    

Permissions for a channel type can be updated either by using predefined values or creating new ones. Please check Permission policies page for available fields.


import { Permission } from 'stream-chat';

const update = await client.updateChannelType("public", {
    permissions: [
        new Permission(
            name: 'Allow reads for all',
            priority: 999,
            resources: ['ReadChannel', 'CreateMessage'],
            AnyRole
        ),
        DenyAll
    ]
});
                    

$channelConf = [
    '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
];

$update = $client->updateChannelType('channel-id', $channelConf);
                    

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=["*"], action="Deny"),
    ],
)
                    

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

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.