Create channels
Channel naming
Before creating channels, take the time to carefully plan your naming strategy. Stick to consistent naming conventions and structure your channels thoughtfully. This preparation helps you avoid increased complexity, performance bottlenecks, and scalability issues, ensuring your app remains manageable and efficient as it grows.
Create channels (Channel
objects) of one of these types:
Requires App Context
To store data about channels, you must enable App Context for your app's keyset in the Admin Portal.
No support for channel groups
Chat SDKs don't support channel groups. We recommend using a Core SDK to manage channel groups.
Create direct channel
Direct channels enable private conversations between two users, letting one person initiate the chat and send an invitation to another person for:
-
Personal conversations - you can engage in private conversations with friends, family, or colleagues, sharing personal updates, discussing sensitive matters, or planning social events.
-
Professional collaboration - you can use 1:1 chat to have focused discussions, exchange confidential information, provide feedback, or coordinate tasks with colleagues and business partners.
CreateDirectConversation()
is a method that:
- Creates a
direct
(one-on-one) channel type. - Sets channel membership for the channel owner (so that they can join the channel).
- Invites the other user to join the channel. As a result, an event of the
invite
type gets created. You can listen to these events in your chat app and notify the invited users.
If you call this method to create a channel for users that already had a conversation which was not deleted, this conversation is retrieved.
Receive messages
Note that you still have to call the Connect()
method to subscribe to message event listeners and start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.CreateDirectConversation(
2 User user,
3 string channelId = "",
4 ChatChannelData? channelData = null,
5 ChatMembershipData? membershipData = null)
6
7public class ChatChannelData
8{
9 public string Name { get; set; } = string.Empty;
10 public string Description { get; set; } = string.Empty;
11 public Dictionary<string, object> CustomData { get; set; } = new ();
12 public string Updated { get; internal set; } = string.Empty;
13 public string Status { get; set; } = string.Empty;
14 public string Type { get; set; } = string.Empty;
15}
Input
Parameter | Description |
---|---|
user *Type: User Default: n/a | User that you invite to join a channel. |
channelId Type: string Default: Guid.NewGuid() | ID of the direct channel. If no value is provided a random Guid() will be generated and set as the Channel ID. |
channelData Type: object Default: null | Information about the channel. |
→ Name Type: string Default: string.Empty | Display name for the channel. |
→ Description Type: string Default: string.Empty | Additional details about the channel. |
→ CustomData Type: Dictionary<string, object> Default: new () | Any custom properties or metadata associated with the channel. |
→ Updated Type: string Default: string.Empty | Timestamp indicating when the channel was last updated or modified. |
→ Status Type: string Default: string.Empty | Current status of the channel, such as online , offline , or archived . |
→ Type Type: string Default: string.Empty | Type of the channel, like direct . |
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
This method returns a Task<ChatOperationResult<CreatedChannelWrapper>>
with the following data:
Parameter | Description |
---|---|
CreatedChannel Type: Channel | Returned object containing the updated channel metadata. |
HostMembership Type: Membership | Returned object containing the updated host (channel owner) metadata. |
InviteesMemberships Type: List<Membership> | Single-item list containing the updated data of the invited user. |
Sample code
Invite agent-007
to a 1:1 conversation to talk about customer XYZ
.
1
Create group channel
Group channels enable communication among multiple users, promoting collaboration and teamwork. A user can initiate a group chat and invite others to be channel members for:
-
Team collaboration - members of a project team can use group chat to share updates, exchange ideas, ask questions, and provide status updates. This boosts real-time collaboration and productivity and ensures everyone stays on the same page.
-
Community building - group chat allows like-minded individuals to connect, discuss shared interests, organize events, and build strong communities around specific topics, hobbies, or professional fields.
Such a chat type is restricted by invitation, and you can access it only when invited.
CreateGroupConversation()
is a method that:
- Creates a
group
channel type. - Sets channel membership for the channel owner (so that they can join the channel).
- Invites other users to join the channel.
Receive messages
Note that you still have to call the Connect()
method to subscribe to message event listeners and start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.CreateGroupConversation(
2 List<User> users,
3 string channelId = "",
4 ChatChannelData? channelData = null,
5 ChatMembershipData? membershipData = null)
6
7public class ChatChannelData
8{
9 public string Name { get; set; } = string.Empty;
10 public string Description { get; set; } = string.Empty;
11 public Dictionary<string, object> CustomData { get; set; } = new ();
12 public string Updated { get; internal set; } = string.Empty;
13 public string Status { get; set; } = string.Empty;
14 public string Type { get; set; } = string.Empty;
15}
Input
Parameter | Description |
---|---|
users *Type: List<User> Default: n/a | List of users that you invite to join a channel. You can invite a maximum number of 100 users at once as this is the limitation set by the App Context API that the InviteMultiple() method calls. |
channelId Type: string Default: Guid.NewGuid() | ID of the group channel. If no value is provided a random Guid() will be generated and set as the Channel ID. |
channelData Type: ChatChannelData Default: null | Information about the channel. |
→ Name Type: string Default: string.Empty | Display name for the channel. |
→ Description Type: string Default: string.Empty | Additional details about the channel. |
→ CustomData Type: Dictionary<string, object> Default: new () | Any custom properties or metadata associated with the channel. |
→ Updated Type: string Default: string.Empty | Timestamp indicating when the channel was last updated or modified. |
→ Status Type: string Default: string.Empty | Current status of the channel, such as online , offline , or archived . |
→ Type Type: string Default: string.Empty | Type of the channel, like group . |
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
This method returns a Task<ChatOperationResult<CreatedChannelWrapper>>
with the following data:
Parameter | Description |
---|---|
CreatedChannel Type: Channel | Returned object containing the updated channel metadata. |
HostMembership Type: Membership | Returned object containing the updated host (channel owner) data. |
InviteesMemberships Type: List<Membership> | Returned object containing the updated metadata of the invited users. |
Sample code
Create a group conversation and invite agent-007
and agent-008
to have weekly syncs on customer XYZ
.
1
Create public channel
Supported features
The public channel type comes with certain limitations in place - you'll get errors when trying to implement such Unity Chat SDK features as typing indicator or read receipts in public channels since these features are neither useful nor practical for large audiences.
Public channels let users engage in open conversations with many people. Unlike group chats, anyone can join public channels. Example use cases include:
-
Knowledge sharing and Q&A - public chats provide a platform for users to seek advice, share knowledge, and participate in discussions related to specific topics, fostering a community-driven environment.
-
Events and webinars - organizations can host public chats during live events, webinars, or panel discussions, allowing attendees to interact with presenters, ask questions, and share insights in real time.
CreatePublicConversation()
is a method that creates such a public
channel type with specified metadata.
Receive messages
Note that you still have to call the Connect()
method to subscribe to message event listeners and start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.CreatePublicConversation(
2 string channelId = "",
3 ChatChannelData? additionalData = null
4)
5
6public class ChatChannelData
7{
8 public string Name { get; set; } = string.Empty;
9 public string Description { get; set; } = string.Empty;
10 public Dictionary<string, object> CustomData { get; set; } = new ();
11 public string Updated { get; internal set; } = string.Empty;
12 public string Status { get; set; } = string.Empty;
13 public string Type { get; set; } = string.Empty;
14}
Input
Parameter | Description |
---|---|
channelId Type: string Default: Guid.NewGuid() | ID of the group channel. If no value is provided a random Guid() will be generated and set as the Channel ID. |
channelData Type: ChatChannelData Default: null | Information about the channel. |
→ Name Type: string Default: string.Empty | Display name for the channel. |
→ Description Type: string Default: string.Empty | Additional details about the channel. |
→ CustomData Type: Dictionary<string, object> Default: new () | Any custom properties or metadata associated with the channel. |
→ Updated Type: string Default: string.Empty | Timestamp indicating when the channel was last updated or modified. |
→ Status Type: string Default: n/a | Current status of the channel, such as online , offline , or archived . |
→ Type Type: string Default: n/a | Type of the channel, like public . |
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
Type | Description |
---|---|
Task<ChatOperationResult<Channel>> | Async task with the created Channel object. |
Sample code
Create a public ask-support
channel.
1