On this page

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:

Direct (1:1)
Group
Public

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 direct type
Sets channel membership for the channel owner
Invites the other user (generates an invite event)

If a conversation between the two users already exists, the method returns that existing channel.

Receive messages

Call connect() to start receiving messages on the channel.

Method signature

This method takes the following parameters:

1chat.createDirectConversation(
  invitedUser: User,
  channelId: String?,
  channelName: String?,
  channelDescription: String?,
  channelCustom: CustomObject?,
  channelStatus: String?,
  membershipCustom: CustomObject?,
9): PNFuture<CreateDirectConversationResult>

Input

* required

Parameter	Description
`invitedUser` * Type: `User` Default: n/a	User that you invite to join a channel.
`channelId` Type: `String` Default: Automatically generated ID	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 the `direct` prefix in front. For example, `direct.1234567890`. You can override this default value by providing your own ID.
`channelName` Type: `String` Default: n/a	Display name for the channel. If you don't provide the name, the channel will get the same name as `id` (value of `channelId`).
`channelDescription` Type: `String` Default: n/a	Additional details about the channel.
`channelCustom` Type: `CustomObject` Default: n/a	Any custom properties or metadata associated with the channel in the form of a JSON object. Values must be scalar only; arrays or objects are not supported. App Context filtering language doesn’t support filtering by custom properties.
`channelStatus` Type: `String` Default: n/a	Current status of the channel, like `online`, `offline`, or `archived`.
`membershipCustom` Type: `CustomObject` Default: n/a	Any custom properties or metadata associated with the user-channel membership in the form of a JSON object. 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

Type	Description
`PNFuture<CreateDirectConversationResult>`	`PNFuture` containing the newly created channel object.

Sample code

Invite agent-007 to a 1:1 conversation to talk about customer XYZ.

1chat.createDirectConversation(
  invitedUser = userAgent7,
  channelName = "Quick sync on customer XYZ",
  channelCustom = mapOf("purpose" to "premium-support")
5).async { result ->
  result.onSuccess {
      // handle success
  }.onFailure {
      // handle failure
  }
11}

Create 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 group type
Sets channel membership for the channel owner
Invites other users to join

Receive messages

Call connect() to start receiving messages on the channel.

Method signature

This method takes the following parameters:

1chat.createGroupConversation(
  invitedUsers: Collection<User>,
  channelId: String?,
  channelName: String?,
  channelDescription: String?,
  channelCustom: CustomObject?,
  channelStatus: String?,
  custom: CustomObject?,
9): PNFuture<CreateGroupConversationResult>

Input

* required

Parameter	Description
`invitedUser` * Type: `Collection<User>` Default: n/a	Users that you invite to join a channel.
`channelId` Type: `String` Default: Automatically generated ID	ID of the group channel. The channel ID is created automatically using the v4 UUID generator. You can override it by providing your own ID.
`channelName` Type: `String` Default: n/a	Display name for the channel. If you don't provide the name, the channel will get the same name as `id` (value of `channelId`).
`channelDescription` Type: `String` Default: n/a	Additional details about the channel.
`channelCustom` Type: `CustomObject` Default: n/a	Any custom properties or metadata associated with the channel in the form of a JSON object. Values must be scalar only; arrays or objects are not supported. App Context filtering language doesn’t support filtering by custom properties.
`channelStatus` Type: `String` Default: n/a	Current status of the channel, like `online`, `offline`, or `archived`.
`membershipCustom` Type: `CustomObject` Default: n/a	Any custom properties or metadata associated with the user-channel memberships in the form of a JSON object. 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

Type	Description
`PNFuture<CreateGroupConversationResult>`	`PNFuture` containing the newly created channel object.

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
2val invitedUsers = listOf(userAgent7, userAgent8)
3// add the channel ID, name, and topic
4chat.createGroupConversation(
5    invitedUsers = invitedUsers,
6    channelName = "Quick sync on customer XYZ",
7    channelCustom = mapOf("purpose" to "premium-support")
8).async { result ->
9    result.onSuccess {
10        // handle success
11    }.onFailure {
12        // handle failure
13    }
14}

Create 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 connect() to start receiving messages on the channel.

Method signature

This method takes the following parameters:

1chat.createPublicConversation(
  channelId: String?,
  channelName: String?,
  channelDescription: String?,
  channelCustom: CustomObject?,
  channelStatus: String?,
7): PNFuture<Channel>

Input

* required

Parameter	Description
`channelId` Type: `String` Default: Automatically generated UUIDv4	ID of the public channel. The channel ID is created automatically using the v4 UUID generator. You can override it by providing your own ID.
`channelName` Type: `String` Default: n/a	Display name for the channel. If you don't provide the name, the channel will get the same name as `id` (value of `channelId`).
`channelDescription` Type: `String` Default: n/a	Additional details about the channel.
`channelCustom` Type: `CustomObject` Default: n/a	Any custom properties or metadata associated with the channel in the form of a JSON object. Values must be scalar only; arrays or objects are not supported. App Context filtering language doesn’t support filtering by custom properties.
`channelStatus` Type: `String` Default: n/a	Current status of the channel, like `online`, `offline`, or `archived`.

API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Output

Type	Description
`PNFuture<Channel>`	`PNFuture` containing the created channel metadata.

Sample code

Create a public ask-support channel.

1// define the channel ID, name, and description
2val channelId = "support-channel-4"
3val channelName = "ask-support"
4val channelDescription = "Space dedicated to answering all support-related questions"
5

6chat.createPublicConversation(
7    channelId = channelId,
8    channelName = channelName,
9    channelDescription = channelDescription
10).async { result ->
11    result.onSuccess {
12        // handle success
13    }.onFailure {
14        // handle failure
15    }
16}
show all 16 lines

Channel naming

Requires App Context

No support for channel groups

Create direct channel​

Receive messages

Method signature​

Input​

API limits

Output​

Sample code​

Create group channel​

Receive messages

Method signature​

Input​

API limits

Output​

Sample code​

Create public channel​

Supported features

Receive messages

Method signature​

Input​

API limits

Output​

Sample code​

Create direct channel

Method signature

Input

Output

Sample code

Create group channel

Method signature

Input

Output

Sample code

Create public channel

Method signature

Input

Output

Sample code