Skip to main content

Channels

ChatKitty organizes conversations into dedicated contexts called channels. Channels structure and order your application's chat experience. You can create a channel for any topic, project, or team.

After a user joins a channel, the user becomes a channel member. ChatKitty broadcasts messages created in channels to channel members with active chat sessions and sends push notifications to offline members. ChatKitty persists messages sent in a channel by default but this behaviour can be configured.

Schema​

type
required
string

The type of this channel

id
required
integer <int64>

64-bit integer identifier associated with this resource

created_time
required
string <date-time>

The ISO date-time this channel was created

object (ChatUserProperties)
display_name
required
string

Human readable name of this channel shown to users

object (MessageProperties)
name
required
string

The unique name of this channel used to reference the channel

required
object

Custom data associated with this channel

Array of objects (Link)

Hypermedia control links for this resource

Example
{}

Channel types​

There are three types of channels:

Direct Channels​

Direct channels let users have private one-on-one conversations with other users. New users cannot be added to a direct channel and there can only exist one direct channel between a set of users.

note

A direct channel can have up to 10 members. Public and private channels are better suited for group chats; supporting up to millions of members.

Public Channels​

Public channels let users discuss topics openly. By default, any user can view and join a public channel. Users can join public channels by themselves or via invites from an existing channel member.

Private Channels​

Private channels are for topics that should not be open to all members. Users must be added to a private channel by someone who's already a member of the channel.

Creating a channel​

Create a new channel of channel type (DIRECT, PUBLIC, or PRIVATE) with a unique name for public and private channels and member references for direct channels. A user is automatically a member of a channel they created.

Creating a direct channel

Using the Platform API

POST /v1/channels
curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/channels' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "PUBLIC",
  "name": "b0a0bd55-921a-4f72-8ee3-f26c6fda0bb7"
}'

Using a client SDK

Creating a direct channel

const result = await chatkitty.createChannel({
  type: 'DIRECT',
  members: [
    { username: 'jane@chatkitty.com' },
    { username: 'john@chatkitty.com' },
  ],
});

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Creating a public channel

const result = await chatkitty.createChannel({
  type: 'PUBLIC',
  name: 'my-first-public-channel',
});

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Creating a private channel

const result = await chatkitty.createChannel({
  type: 'PRIVATE',
  name: 'my-first-private-channel',
});

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Listing channels​

Get all channels accessible to the current user regardless of current membership status.

Using a Client SDK

const result = await chatkitty.listChannels();

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

Using the Platform API

GET /v1/channels
curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels?page=0&size=5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Listing joined channels​

Get channels the current user has joined (is already a member) and can start chat sessions in.

const result = await chatkitty.listChannels({ filter: { joined: true } });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

Listing joinable channels​

Get channels the current user can join, becoming a member.

const result = await chatkitty.listChannels({ filter: { joined: false } });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

Retrieving a channel​

Get a channel by searchable properties like channel ID

const result = await chatkitty.retrieveChannel(channelId);

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Joining a public channel​

const result = await chatkitty.joinChannel({ channel });

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Observing user joined channel​

When the current user joins a channel or is added to a channel by another user or through the Platform API, registered channel observers are notified.

const unsubscribe = chatkitty.onChannelJoined((channel) => {
  // handle channel
});

// call when you're no longer interested in updates
unsubscribe();

Reading a channel​

Read a channel to automatically read all channel messages.

const result = await chatkitty.readChannel({ channel });

if (result.succeeded) {
  const channel = result.channel; // Handle channel
}

if (result.failed) {
  const error = result.error; // Handle error
}

Checking if a channel is unread​

A channel is unread if it has any unread messages by the current user.

const result = await chatkitty.checkChannelUnread({
  channel: channel,
});

if (result.succeeded) {
  const unread = result.unread; // Handle if unread
}

Updating channel properties​

Update the customisable properties object for any channel using the Platform API. Properties is a JSON object.

PATCH /v1/channels/{id}

Add the desired property to the request body here.

curl -X 'PATCH' \
  'https://api.chatkitty.com/v1/channels/135302' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 0532dd12-ca09-462e-b0c5-dc8cb9628bd1' \
  -H 'Content-Type: application/json+merge-patch' \
  -d '{
  "properties": {"PROPERTY_KEY":"PROPERTY_VALUE"}
}'

Searching for channels​

Get any channels by searching through list of channels.

Searching with filters​

Group channels can be searched by name, joined, and unread using a filter through the client SDK. Direct channels can be searched by joined and unread using a filter through the client SDK.

If joined:

const result = await chatkitty.listChannels({ filter: { joined: true } });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

If unread:

const result = await chatkitty.listChannels({ filter: { unread: true } });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

By name:

const result = await chatkitty.listChannels({ filter: { name: string } });

if (result.succeeded) {
  const channels = result.paginator.items; // Handle channels
}

if (result.failed) {
  const error = result.error; // Handle error
}

Searching by values in the properties object​

Channels can also be search for by values in their properties field using the Platform API. See updating channels to add customisable properties to channels.

Using the Platform API:

GET v1/channels?properties=SEARCH_TERM
info

Where SEARCH_TERM is searchKey:searchValue in the string format.

curl -X 'GET' \
  'https://api.chatkitty.com/v1/channels?page=0&size=25&properties=mySearchableProperty%3A%22mySearchableValue%22' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 0532dd12-ca09-462e-b0c5-dc8cb9628bd1'

Deleting a channel​

Delete a channel and all its related resources

const result = await chatkitty.deleteChannel({
  channel: channel
});

if (result.succeeded) {
  // Handle result
}