Creating Channels

Both channel channel.create and channel.watch methods ensure that a channel exists and create one otherwise. If all you need is to ensure that a channel exists, you can use channel.create. This is allowed server-side and client-side, however, is more commonly used server-side. Client-side integrations favor channel.watch as it both creates and watches the channel in one call. See: Watching A Channel

Channels are unique either by specifying a channel ID or list of members in the create request.

1. Creating a Channel Using a Channel Id

This is the best approach if you already have some sort of object in your database that the channel is associated with. As an example, if you’re building a live-streaming service like Twitch you have a channel for every streamer in your database.

val channelClient = client.channel(channelType = "messaging", channelId = "general")

channelClient.create(memberIds = emptyList(), extraData = emptyMap()).enqueue { result ->
  if (result.isSuccess) {
    val newChannel: Channel = result.data()
  } else {
    // Handle result.error()
  }
}

const channel = client.channel("messaging", "travel", {
  name: "Awesome channel about traveling",
});
// Here, 'travel' will be the channel ID
await channel.create();

/// 1: Create a `ChannelId` that represents the channel you want to create.
let channelId = ChannelId(type: .messaging, id: "general")

/// 2: Use the `ChatClient` to create a `ChatChannelController` with the `ChannelId`.
let channelController = chatClient.channelController(for: channelId)

/// 3: Call `ChatChannelController.synchronize` to create the channel.
channelController.synchronize { error in
  if let error = error {
    /// 4: Handle possible errors
    print(error)
  }
}

final channel = client.channel(
 "messaging",
 id: "travel",
 extraData: {
  "name": "Founder Chat",
  "image": "http://bit.ly/2O35mws",
  "members": ["thierry", "tommaso"],
 },
);

const channel = client.channel("messaging", "travel", {
  name: "Awesome channel about traveling",
  created_by_id: "myuserid",
});
await channel.create();

# Note: 'channel_id' parameter must be named!
channel = client.channel('messaging', channel_id: 'general')

channel.create('jlahey')

const FChannelProperties Properties{
  TEXT("messaging"),  // Type
  TEXT("travel"),    // Id
};
Client->CreateChannel(
  Properties,
  [](UChatChannel* Channel)
  {
    // Channel created
  });

channel = client.channel("messaging", "travel")
channel.create("myuserid")

$channel = $client->Channel("messaging", "general");
$channel->create("thierry");

var chanData = new ChannelRequest { CreatedBy = new UserRequest { Id = "thierry" } };
await channelClient.GetOrCreateAsync("messaging", "general", new ChannelGetRequest
{
  Data = chanData,
});

client.CreateChannel(ctx, "messaging", "general", "tommaso", nil)

var channel = await Client.GetOrCreateChannelWithIdAsync(ChannelType.Messaging, "my-channel-id");

//Once you get or query a channel it is also added to Client.WatchedChannels list

// Android SDK
ChannelClient channelClient = client.channel("messaging", "general");

Map<String, Object> extraData = new HashMap<>();
List<String> memberIds = new LinkedList<>();

channelClient.create(memberIds, extraData)
    .enqueue(result -> {
      if (result.isSuccess()) {
        Channel newChannel = result.data();
      } else {
       // Handle result.error()
     }
   });

// Backend SDK
ChannelGetResponse channel = Channel.getOrCreate("messaging", "general")
  .data(
    ChannelRequestObject.builder()
      .createdBy(someUser)
      .additionalField("custom_field", "custom_value") // Optional custom fields
      .build())
  .request()

2. Creating a Channel for a List of Members - distinct channels

Channels can be used to create conversations between users. In most cases, you want conversations to be unique and make sure that a group of users have only one channel. These are also referred to as ‘distinct channels’.

You can achieve this by leaving the channel ID empty and providing channel type and members. When you do so, the API will ensure that only one channel for the members you specified exists (the order of the members does not matter).

client.createChannel(
  channelType = "messaging",
  channelId = "",
  memberIds = listOf("thierry", "tomasso"),
  extraData = emptyMap()
).enqueue { result ->
   if (result.isSuccess) {
     val channel = result.data()
   } else {
     // Handle result.error()
   }
}

const channel = client.channel("messaging", {
  members: ["thierry", "tommaso"],
});
await channel.create();

client.channel("messaging", extraData: {"members": ["thierry", "tommaso"]});

/// 1: Use the `ChatClient` to create a `ChatChannelController` with a list of user ids
let channelController = try chatClient.channelController(
  createDirectMessageChannelWith: ["thierry", "tomasso"],
  extraData: [:]
)

/// 2: Call `ChatChannelController.synchronize` to create the channel.
channelController.synchronize { error in
  if let error = error {
    /// 4: Handle possible errors
    print(error)
  }
}

const channel = client.channel("messaging", {
  members: ["thierry", "tommaso"],
  created_by_id: "myuserid",
});
await channel.create();

$conversation = $client->Channel('messaging', 'thierry-jenny', ['members'=>['thierry', 'jenny']]);
$state  = $conversation->create('thierry');

# Note: 'channel_id' and 'data' parameters must be named!

channel = client.channel(
  'messaging',
  channel_id: 'thierry-tommaso-1',
  data: {
   'name'  => 'Founder Chat',
   'image' => 'http://bit.ly/2O35mws',
   'members' => ['thierry', 'tommaso'],
  }
)

channel.create('thierry')

const FChannelProperties Properties = FChannelProperties{TEXT("messaging")}
            .SetMembers({TEXT("thierry"), TEXT("tommaso")});
Client->CreateChannel(
  Properties,
  [](UChatChannel* Channel)
  {
    // Channel created
  });

channel = client.channel("messaging", "travel", custom_data=dict(members=["thierry"]))
channel.create("myuserid")

$channel = $client->Channel(
  "messaging",
  null,
  ["members" => ["thierry", "tommaso"]]
);
$channel->create("thierry");

var chanData = new ChannelRequest { CreatedBy = new UserRequest { Id = "thierry" } };
await channelClient.GetOrCreateAsync("messaging", new ChannelGetRequest
{
  Data = chanData,
});

client.CreateChannel(ctx, "messaging", nil, "tommaso", map[string]interface{}{
		"members": []string{"thierry", "tommaso"},
})

var filters = new IFieldFilterRule[]
{
  UserFilter.Id.EqualsTo("other-user-id")
};
// Find user you want to start a chat with
var users = await Client.QueryUsersAsync(filters);

var otherUser = users.First();
var localUser = Client.LocalUserData.User;

// Start direct channel between 2 users
var channel = await Client.GetOrCreateChannelWithMembersAsync(ChannelType.Messaging, new[] { localUser, otherUser});

// Android SDK
ChannelClient channelClient = client.channel("messaging", "");

Map<String, Object> extraData = new HashMap<>();
List<String> memberIds = new LinkedList<>();
memberIds.add("thierry");
memberIds.add("tomasso");

channelClient.create(memberIds, extraData)
    .enqueue(result -> {
      if (result.isSuccess()) {
        Channel newChannel = result.data();
      } else {
       // Handle result.error()
     }
   });

// Backend SDK
List<ChannelMemberRequestObject> memberList = new ArrayList<>();
testUsersRequestObjects.add(
  ChannelMemberRequestObject.builder().user(user1).build());
testUsersRequestObjects.add(
  ChannelMemberRequestObject.builder().user(user2).build());

ChannelGetResponse channel = Channel.getOrCreate("messaging", null)
  .data(
    ChannelRequestObject.builder()
      .createdBy(someUser)
      .members(memberList)
      .build())
  .request()

Channel Data

When you create a channel using one of the above approaches you’ll specify the following fields:

The channel data can contain as many custom fields as you’d like as long as the total size is below 5KB. Note that you typically upload images to a CDN. So the 5KB limit only applies to the text data specified on the channel. Members is a reserved field, and our UI libraries use name and image to display the channels.