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 1:1 conversations. Use cases include personal conversations and professional collaboration.
createDirectConversation() performs these actions:
- Creates a channel with the
directtype - Sets channel membership for the channel owner
- Invites the other user (generates an
inviteevent)
If a conversation between the two users already exists, the method returns that existing channel.
Receive messages
Call onMessageReceived() to start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.createDirectConversation({ user, channelData, membershipData, }: {
2 user: User,
3 channelId?: string
4 channelData?: {
5 name?: string,
6 description?: string,
7 custom?: ObjectCustom
8 },
9 membershipData?: {
10 custom: ObjectCustom
11 }
12}): Promise<{
13 channel: Channel,
14 hostMembership: Membership,
15 inviteeMembership: Membership,
show all 16 linesInput
userrequired#- User that you invite to join a channel.
channelId#- ID of the direct channel. The channel ID is created automatically by a hashing function that takes the string of two user names joined by
&, computes a numeric value based on the characters in that string, and adds thedirectprefix in front. For example,direct.1234567890. You can override this default value by providing your own ID. channelData#- Information about the channel.
- property of channelData:
name# - Display name for the channel.
If you don't provide the name, the channel will get the same name asid(value ofchannelId). - property of channelData:
description# - Additional details about the channel.
- property of channelData:
custom# - Any custom properties or metadata associated with the channel.
membershipData#- Information about the user-channel membership.
- property of membershipData:
customrequired# - Any custom properties or metadata associated with the channel membership in the form of a JSON. Values must be scalar only; arrays or objects are not supported. App Context filtering language doesn’t support filtering by custom properties.
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
Promise<>#- Returned object containing these fields:
channel,hostMembership, andinviteeMembership. - property of Promise<>:
channel# - Returned object containing the updated channel metadata.
- property of Promise<>:
hostMembership# - Returned object containing the updated host (channel owner) metadata.
- property of Promise<>:
inviteeMembership# - Returned object containing the updated data of the invited user.
Sample code
Invite agent-007 to a 1:1 conversation to talk about customer XYZ.
1// reference the person you want to talk to
2const userToChatWith = await chat.getUser("agent-007")
3
4// add the channel name and topic
5const { channel, hostMembership, inviteeMembership } = await chat.createDirectConversation(
6 {
7 user: userToChatWith,
8 channelData: {
9 name: "Quick sync on customer XYZ"
10 },
11 membershipData: {
12 custom: {
13 purpose: "premium-support"
14 }
15 }
show all 17 linesCreate group channel
Group channels enable multi-user conversations for team collaboration and community building. Access requires an invitation.
createGroupConversation() performs these actions:
- Creates a channel with the
grouptype - Sets channel membership for the channel owner
- Invites other users to join
Receive messages
Call onMessageReceived() to start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.createGroupConversation({ users, channelId, channelData, membershipData, }: {
2 users: User[],
3 channelId?: string
4 channelData?: {
5 name?: string,
6 description?: string,
7 custom?: ObjectCustom
8 },
9 membershipData?: {
10 custom: ObjectCustom
11 }
12}): Promise<{
13 channel: Channel,
14 hostMembership: Membership,
15 inviteesMemberships: Membership[],
show all 16 linesInput
usersrequired#- 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#- ID of the group channel. The channel ID is created automatically using the UUIDv4 module. You can override it by providing your own ID.
channelData#- Information about the channel.
- property of channelData:
name# - Display name for the channel.
If you don't provide the name, the channel will get the same name asid(value ofchannelId). - property of channelData:
description# - Additional details about the channel.
- property of channelData:
custom# - Any custom properties or metadata associated with the channel.
membershipData#- Information about the user-channel memberships.
- property of membershipData:
customrequired# - Any custom properties or metadata associated with the channel membership in the form of a JSON. Values must be scalar only; arrays or objects are not supported. App Context filtering language doesn’t support filtering by custom properties.
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
Promise<>#- Returned object containing these fields:
channel,hostMembership, andinviteeMembership. - property of Promise<>:
channel# - Returned object containing the updated channel metadata.
- property of Promise<>:
hostMembership# - Returned object containing the updated host (channel owner) data.
- property of Promise<>:
inviteesMemberships# - 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// reference both agents you want to talk to
2const user1 = await chat.getUser("agent-007")
3const user2 = await chat.getUser("agent-008")
4
5// add the channel ID, name, and topic
6const { channel, hostMembership, inviteesMemberships } = await chat.createGroupConversation(
7 {
8 users:
9 [
10 user1,
11 user2
12 ],
13 channelId: "group-chat-1"
14 channelData: {
15 name: "Weekly syncs on customer XYZ"
show all 23 linesCreate public channel
Public channels are open to anyone without invitation. Use cases include Q&A forums, knowledge sharing, and live event chat.
Supported features
Public channels do not support typing indicators or read receipts. These features are impractical for large audiences.
createPublicConversation() creates a channel with the public type and the specified metadata.
Receive messages
Call onMessageReceived() to start receiving messages on the channel.
Method signature
This method takes the following parameters:
1chat.createPublicConversation({ channelId, channelData, }: {
2 channelId?: string
3 channelData?: {
4 name?: string,
5 description?: string,
6 custom?: ObjectCustom
7 }
8}): Promise<Channel>
Input
channelId#- ID of the public channel. The channel ID is created automatically using the UUIDv4 module. You can override it by providing your own ID.
channelData#- Information about the channel.
- property of channelData:
name# - Display name for the channel.
If you don't provide the name, the channel will get the same name asid(value ofchannelId). - property of channelData:
description# - Additional details about the channel.
- property of channelData:
custom# - Any custom properties or metadata associated with the channel.
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Output
| Type | Description |
|---|---|
Promise<Channel> | Object returning the created channel metadata. |
Sample code
Create a public ask-support channel.
1const = await chat.createPublicConversation(
2 {
3 channelId: "support-channel-4"
4 channelData: {
5 name: "ask-support"
6 description: "Space dedicated to answering all support-related questions"
7 }
8 }
9)