Create channels

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.

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:

chat.createDirectConversation(
    invitedUser: UserImpl,
    channelId: String? = nil,
    channelName: String? = nil,
    channelDescription: String? = nil,
    channelCustom: [String: JSONCodableScalar]? = nil,
    channelStatus: String? = nil,
    membershipCustom: [String: JSONCodableScalar]? = nil,
    completion: ((Swift.Result<CreateDirectConversationResult<ChannelImpl, MembershipImpl>, Error>) -> Void)? = nil
)

Input

Parameter	Type	Required	Default	Description
`invitedUser`	`UserImpl`	Yes	n/a	User that you invite to join a channel.
`channelId`	`String`	No	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`	`String`	No	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`	`String`	No	n/a	Additional details about the channel.
`channelCustom`	`[String: JSONCodableScalar]`	No	n/a	Any custom properties or metadata associated with the channel 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.
`channelStatus`	`String`	No	n/a	Current status of the channel, like `online`, `offline`, or `archived`.
`membershipCustom`	`[String: JSONCodableScalar]`	No	n/a	Any custom properties or metadata associated with the user-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

Parameter	Type	Description
`CreateDirectConversationResult`	`object`	Returned object containing these fields: `channel`, `hostMembership`, and `inviteeMembership`.
→ `channel`	`ChannelImpl`	Returned object containing the updated channel metadata.
→ `hostMembership`	`MembershipImpl`	Returned object containing the updated host (channel owner) metadata.
→ `inviteeMembership`	`MembershipImpl`	Returned object containing the updated data of the invited user.

Basic usage

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

/// Assuming you have a "chat" instance available and a "UserImpl" representation of "agent-007" 
let agent007 = UserImpl(chat: chat, id: "agent-007")

/// Invoke the "createDirectConversation()" method to invite "agent-007"
chat?.createDirectConversation(
  invitedUser: agent007,
  channelCustom: ["purpose": "customer XYZ"]
) {
  switch $0 {
  case let .success(conversationResult):
    let channel = conversationResult.channel
    debugPrint("Direct conversation created with channel ID: \(channel.id)")
  case let .failure(error):
    debugPrint("Failed to create direct conversation: \(error)")
  }
show all 16 lines

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:

chat.createGroupConversation(
    invitedUsers: [UserImpl],
    channelId: String? = nil,
    channelName: String? = nil,
    channelDescription: String? = nil,
    channelCustom: [String: JSONCodableScalar]? = nil,
    channelStatus: String? = nil,
    custom: [String: JSONCodableScalar]? = nil,
    completion: ((Swift.Result<CreateGroupConversationResult<ChannelImpl, MembershipImpl>, Error>) -> Void)? = nil
)

Input

Parameter	Type	Required	Default	Description
`invitedUsers`	`[UserImpl]`	Yes	n/a	Users that you invite to join a channel.
`channelId`	`String`	No	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`	`String`	No	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`	`String`	No	n/a	Additional details about the channel.
`channelCustom`	`[String: JSONCodableScalar]`	No	n/a	Any custom properties or metadata associated with the channel 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.
`channelStatus`	`String`	No	n/a	Current status of the channel, like `online`, `offline`, or `archived`.
`custom`	`[String: JSONCodableScalar]`	No	n/a	Any custom properties or metadata associated with the user-channel memberships 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

Parameter	Type	Description
`CreateGroupConversationResult`	`object`	Returned object containing these fields: `channel`, `hostMembership`, and `inviteeMembership`.
→ `channel`	`ChannelImpl`	Returned object containing the updated channel metadata.
→ `hostMembership`	`MembershipImpl`	Returned object containing the updated host (channel owner) data.
→ `inviteesMemberships`	`[MembershipImpl]`	Returned object containing the updated metadata of the invited users.

Basic usage

Create a group conversation and invite agent-007 and agent-008 to have weekly syncs on customer XYZ.

/// Assuming you have a `chat` instance available and "UserImpl" representations of "agent-007" and "agent-008"
let agent007 = UserImpl(chat: chat, id: "agent-007")
let agent008 = UserImpl(chat: chat, id: "agent-008")

/// Invoke the "createGroupConversation()" method to invite "agent-007" and "agent-008"
chat?.createGroupConversation(
  invitedUsers: [agent007, agent008],
  channelName: "Weekly Sync on Customer XYZ"
) {
  switch $0 {
  case let .success(conversationResult):
    let channel = conversationResult.channel
    debugPrint("Group conversation created with channel ID: \(channel.id)")
  case let .failure(error):
    debugPrint("Failed to create group conversation: \(error)")
show all 17 lines

Create public channel

Supported features

The public channel type comes with certain limitations in place - you'll get errors when trying to implement such Chat SDK features as typing indicator, invites, 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:

chat.createPublicConversation(
    channelId: String? = nil,
    channelName: String? = nil,
    channelDescription: String? = nil,
    channelCustom: [String: JSONCodableScalar]? = nil,
    channelStatus: String? = nil,
    completion: ((Swift.Result<ChannelImpl, Error>) -> Void)? = nil
)

Input

Parameter	Type	Required	Default	Description
`channelId`	`String`	No	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`	`String`	No	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`	`String`	No	n/a	Additional details about the channel.
`channelCustom`	`[String: JSONCodableScalar]`	No	n/a	Any custom properties or metadata associated with the channel 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.
`channelStatus`	`String`	No	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
`ChannelImpl`	Object returning the created channel metadata.

Basic usage

Create a public ask-support channel.

/// Assuming you have a "chat" instance available
/// Invoke the "createPublicConversation()" method to create an "ask-support" public channel
chat?.createPublicConversation(
  channelName: "ask-support"
) {
  switch $0 {
  case let .success(channel):
    debugPrint("Public conversation created with channel ID: \(channel.id)")
  case let .failure(error):
    debugPrint("Failed to create public conversation: \(error)")
  }
}

Requires App Context

Create direct channel​

Receive messages

Method signature​

Input​

API limits

Output​

Basic usage​

Create group channel​

Receive messages

Method signature​

Input​

API limits

Output​

Basic usage​

Create public channel​

Supported features

Receive messages

Method signature​

Input​

API limits

Output​

Basic usage​

Create direct channel

Method signature

Input

Output

Basic usage

Create group channel

Method signature

Input

Output

Basic usage

Create public channel

Method signature

Input

Output

Basic usage